Request an updated Basic view for a public post

Posts

post /v1/posts/basic/refresh

Requests the latest available public source state for the supported Basic post fields.

Authentication

• ApiKey bearer token

  Send the current Benchmark API key only in the Authorization header.

Request body

• target EntityTarget required

  A Benchmark entity UUID, platform-native ID, handle, or public URL. Platform can be omitted when the URL identifies it. Link targets require a public HTTPS URL or an existing Benchmark link UUID; HTTP, credentials, local/internal hosts, and non-443 ports are rejected.

Responses

• 202

  Fresh stored data or an accepted data request.

• 400

  The request failed validation.

• 401

  The bearer credential is missing or invalid.

• 402

  The organization needs plan or purchased-credit entitlement, has reached its separate monthly spend cap, or cannot cover the operation within the entitled grace floor.

• 403

  The key cannot perform this operation, or the plan must be upgraded to request refreshes.

• 429

  The Cloudflare rate limiter rejected the request.

• 500

  The request failed without exposing internal diagnostics.

• 503

  A required service is unavailable.

Request

cURL

curl --request POST \
  --url "${BENCHMARK_API_BASE_URL}/v1/posts/basic/refresh" \
  --header "Authorization: Bearer ${BENCHMARK_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{"target":{"reference":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"}}'

Response

202

{
  "collection": {
    "id": "20000000-0000-4000-8000-000000000002",
    "status": "queued",
    "dataLevel": "basic",
    "pollUrl": "/v1/collections/20000000-0000-4000-8000-000000000002",
    "expiresAt": "2026-08-31T12:00:00.000Z",
    "statusMessage": "Your data request is queued and will start shortly."
  },
  "dataRequest": {
    "id": "20000000-0000-4000-8000-000000000002",
    "status": "queued",
    "statusMessage": "Your data request is queued and will start shortly.",
    "statusUrl": "/v1/data-requests/20000000-0000-4000-8000-000000000002",
    "resultUrl": "/v1/data-requests/20000000-0000-4000-8000-000000000002/result",
    "nextOperations": {
      "status": {
        "tool": "query",
        "operation": "getDataRequestStatus",
        "input": {
          "dataRequestId": "20000000-0000-4000-8000-000000000002"
        }
      },
      "result": {
        "tool": "mutate",
        "operation": "getDataRequestResult",
        "input": {
          "dataRequestId": "20000000-0000-4000-8000-000000000002"
        }
      }
    }
  }
}