REST API

Jobs and results

Poll pending work and retrieve completed output.

Every execution creates one account-scoped job. The same job resource is returned by the asynchronous execution path and by a `Prefer: wait` request whose wait window expires.

## Poll a job

```http
GET https://data.upscrape.com/jobs/JOB_ID
Authorization: Bearer UPSCRAPE_API_KEY
```

`GET /jobs/:id/result` remains available for compatibility and currently delegates to the same representation.

Jobs are account-scoped. A key from another account cannot retrieve them.

## Pending states

Queued, running, and retrying jobs return HTTP `202`:

```json
{
  "job_id": "job_id",
  "request_id": "job_id",
  "platform": "platform",
  "capability": "platform.capability.action",
  "state": "running"
}
```

Poll with bounded exponential backoff and jitter. A practical starting sequence is 1, 2, 4, 8, then 10 seconds. Stop after an application-defined deadline; timing out your local wait does not cancel the server-side job.

## Completed state

A completed job returns HTTP `200`, `state: "completed"`, `success: true`, a one-item `results` list, billing details, and execution statistics. Capability-specific JSON is under `results[0].data`.

Some supported q-commerce capabilities also include an additive `normalized` object. Raw output remains available and does not depend on normalization succeeding.

## Hosted artifacts

Capabilities that produce large binary files can return a hosted artifact
instead of base64 data:

```json
{
  "artifact_id": "artifact_id",
  "reference": "artifact://artifact_id",
  "delivery": "hosted",
  "kind": "zip",
  "filename": "example.zip",
  "content_type": "application/zip",
  "bytes": 12345678,
  "sha256": "hex_sha256",
  "download_url": "https://data.upscrape.com/archive-artifacts/artifact_id/download?token=...",
  "download_url_expires_at": "2026-09-01T12:00:00Z"
}
```

Download the file from `download_url` as a normal binary HTTP response; do
not decode the job JSON. The link is private, signed, and valid for one hour.
Do not log or share it. If the link expires while the job is retained, poll
`GET /jobs/:id` again to receive a fresh link. Hosted archive files are
retained for 30 days by default.

For Universal Web, `delivery: "auto"` keeps small archives inline and switches
to hosted delivery when the requested asset budgets exceed the inline safety
caps. Set `delivery: "hosted"` to force a downloadable file. Hosted mode
supports up to 50,000,000 bytes per asset and 500,000,000 bytes across archived
assets.

## Failed state

A failed job returns HTTP `200` with `state: "failed"`, `success: false`, and an error object:

```json
{
  "job_id": "job_id",
  "state": "failed",
  "success": false,
  "error": {
    "code": "upstream_error",
    "message": "sanitized failure description"
  },
  "results": null,
  "stats": null
}
```

Inspect the JSON state rather than treating every HTTP `200` poll response as success.

## Unknown jobs

An unknown or inaccessible job ID returns HTTP `404` with the stable `not_found` error code.

Every execution creates one account-scoped job. The same job resource is returned by the asynchronous execution path and by a Prefer: wait request whose wait window expires.

Poll a job

GET https://data.upscrape.com/jobs/JOB_ID
Authorization: Bearer UPSCRAPE_API_KEY

GET /jobs/:id/result remains available for compatibility and currently delegates to the same representation.

Jobs are account-scoped. A key from another account cannot retrieve them.

Pending states

Queued, running, and retrying jobs return HTTP 202:

{
  "job_id": "job_id",
  "request_id": "job_id",
  "platform": "platform",
  "capability": "platform.capability.action",
  "state": "running"
}

Poll with bounded exponential backoff and jitter. A practical starting sequence is 1, 2, 4, 8, then 10 seconds. Stop after an application-defined deadline; timing out your local wait does not cancel the server-side job.

Completed state

A completed job returns HTTP 200, state: "completed", success: true, a one-item results list, billing details, and execution statistics. Capability-specific JSON is under results[0].data.

Some supported q-commerce capabilities also include an additive normalized object. Raw output remains available and does not depend on normalization succeeding.

Hosted artifacts

Capabilities that produce large binary files can return a hosted artifact instead of base64 data:

{
  "artifact_id": "artifact_id",
  "reference": "artifact://artifact_id",
  "delivery": "hosted",
  "kind": "zip",
  "filename": "example.zip",
  "content_type": "application/zip",
  "bytes": 12345678,
  "sha256": "hex_sha256",
  "download_url": "https://data.upscrape.com/archive-artifacts/artifact_id/download?token=...",
  "download_url_expires_at": "2026-09-01T12:00:00Z"
}

Download the file from download_url as a normal binary HTTP response; do not decode the job JSON. The link is private, signed, and valid for one hour. Do not log or share it. If the link expires while the job is retained, poll GET /jobs/:id again to receive a fresh link. Hosted archive files are retained for 30 days by default.

For Universal Web, delivery: "auto" keeps small archives inline and switches to hosted delivery when the requested asset budgets exceed the inline safety caps. Set delivery: "hosted" to force a downloadable file. Hosted mode supports up to 50,000,000 bytes per asset and 500,000,000 bytes across archived assets.

Failed state

A failed job returns HTTP 200 with state: "failed", success: false, and an error object:

{
  "job_id": "job_id",
  "state": "failed",
  "success": false,
  "error": {
    "code": "upstream_error",
    "message": "sanitized failure description"
  },
  "results": null,
  "stats": null
}

Inspect the JSON state rather than treating every HTTP 200 poll response as success.

Unknown jobs

An unknown or inaccessible job ID returns HTTP 404 with the stable not_found error code.