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`.

```bash
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](/scrapers), 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:

```bash
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.

```bash
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.

```json
{
  "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:

```bash
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:

```bash
--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](/docs/api/execute)
- [Implement bounded job polling](/docs/api/jobs)
- [Handle errors and retries](/docs/api/errors)
- [Use the generated OpenAPI contract](/docs/api/openapi)