MCP

Jobs and results

Handle pending jobs and truncated previews.

MCP execution waits for a result by default, for up to approximately 55 seconds. Slow work returns a pending `job_id` instead of holding the request indefinitely.

## Pending work

Call `upscrape_get_job_result` with the returned job ID. Continue with bounded backoff until the tool reports a completed or failed state.

If the capability returns a top-level array, pass `offset` and `limit` to page
through it. The response includes `result_pagination` with the total, returned
count, and `has_more` flag.

Do not call `upscrape_execute` again merely because the first result was pending. The job ID is the durable state handle.

## Result preview limit

MCP result previews are limited to 24 KiB. If a result exceeds that size, the response is explicitly marked as truncated.

For the full representation, use the authenticated REST job endpoint:

```text
GET https://data.upscrape.com/jobs/JOB_ID
```

The same API key can be used directly. An OAuth-backed consumer client should rely on the capabilities exposed by that client rather than exporting its access token.

## Charging

Execution charges the capability's published credit cost once on successful completion. Pending responses, result retrieval, transport retries, and failed jobs do not add another capability charge.

## Cancellation and progress

The server currently selects the JSON response option rather than SSE. It does
not advertise progress or disconnect cancellation; clients use the explicit
job handle and may stop polling without cancelling the worker job. See
[advanced jobs](/docs/mcp/advanced-jobs) for the exact boundary.

MCP execution waits for a result by default, for up to approximately 55 seconds. Slow work returns a pending job_id instead of holding the request indefinitely.

Pending work

Call upscrape_get_job_result with the returned job ID. Continue with bounded backoff until the tool reports a completed or failed state.

If the capability returns a top-level array, pass offset and limit to page through it. The response includes result_pagination with the total, returned count, and has_more flag.

Do not call upscrape_execute again merely because the first result was pending. The job ID is the durable state handle.

Result preview limit

MCP result previews are limited to 24 KiB. If a result exceeds that size, the response is explicitly marked as truncated.

For the full representation, use the authenticated REST job endpoint:

GET https://data.upscrape.com/jobs/JOB_ID

The same API key can be used directly. An OAuth-backed consumer client should rely on the capabilities exposed by that client rather than exporting its access token.

Charging

Execution charges the capability's published credit cost once on successful completion. Pending responses, result retrieval, transport retries, and failed jobs do not add another capability charge.

Cancellation and progress

The server currently selects the JSON response option rather than SSE. It does not advertise progress or disconnect cancellation; clients use the explicit job handle and may stop polling without cancelling the worker job. See advanced jobs for the exact boundary.