Quickstart

This guide makes one REST request, waits briefly for completion, and shows how to continue when the result is still pending.

1. Create an API key

Sign in to the Upscrape console, open API keys, and create a key. The plaintext key is shown once. Store it in your secret manager and expose it to your local process as UPSCRAPE_API_KEY.

export UPSCRAPE_API_KEY="your_key_here"

Never put an API key in browser code, source control, documentation, logs, or a coding-agent prompt.

2. Choose a capability

Open the scraper catalog, select a platform, and copy a capability ID and its example input. Capability input is contract-specific: do not guess fields from another platform.

The examples below use placeholders so this guide never becomes coupled to one special-cased platform:

export UPSCRAPE_CAPABILITY="platform.capability.action"

3. Execute it

Send the capability and input to the canonical data API. Prefer: wait=30 asks Upscrape to wait for up to 30 seconds before returning a pending job.

curl --request POST 'https://data.upscrape.com/execute' \
  --header "Authorization: Bearer $UPSCRAPE_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Prefer: wait=30' \
  --data '{
    "capability": "'"$UPSCRAPE_CAPABILITY"'",
    "input": {}
  }'

Replace {} with the exact example input from the selected platform page.

4. Handle the response

A completed request returns HTTP 200. The extracted payload is in results[0].data; billing and execution statistics are adjacent metadata.

{
  "job_id": "job_id",
  "state": "completed",
  "success": true,
  "results": [
    {"data": {"...": "capability output"}}
  ],
  "billing": {"credits_charged": 1}
}

If the wait expires first, the endpoint returns HTTP 202 and a pending job. Poll it with the same API key:

curl --header "Authorization: Bearer $UPSCRAPE_API_KEY" \
  'https://data.upscrape.com/jobs/JOB_ID'

Stop polling when the state is terminal. Do not create a second execution merely because the first request returned 202.

5. Make retries safe

For application traffic, send an Idempotency-Key unique to the logical operation:

--header 'Idempotency-Key: customer-42-daily-profile-2026-08-06'

Reusing the same key with the same request returns the same logical job. Reusing it with different input is a conflict.

Next steps

• Understand execute responses
• Implement bounded job polling
• Handle errors and retries
• Use the generated OpenAPI contract