Quickstart

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

To see a result right away, create a key (step 1) and run this Google Maps search as is. It costs 1 credit:

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": "googlemaps.search",
    "input": {"query": "coffee shops", "location": "San Francisco, CA", "limit": 5}
  }'

The steps below show how to run any other capability the same way.

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 rest of this guide uses a placeholder for the capability you picked:

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 with a poll_url. Wait poll_after_ms, then 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