REST API

Credits and limits

Understand charging, rate limits, waits, and timeouts.

Each module declares one fixed positive `credits_per_request` value. Every capability in that module is published and charged at that fixed cost.

## When credits are charged

Credits are charged once when a logical job completes successfully.

The completed response also reports `billing.settlement`. A zero charge with a
positive published rate is intentional when settlement is
`included_subscription` or `out_of_band_contract`; it is not evidence that the
capability is free. `zero_charge_requires_review` indicates an unexpected settlement state; contact Upscrape support if it appears in a response.

The following do not add another capability charge:

- a pending response;
- polling a job;
- internal worker retries;
- a failed job;
- an idempotent replay of the same logical request.

Credit reservations prevent concurrent requests from overspending the same remaining balance. A zero balance blocks new execution.

## Find the cost

The public platform page displays the credit cost next to every capability. The value comes from the same published capability contract used during execution, not from page-specific copy.

## Wait limits

REST accepts `Prefer: wait=N` with a maximum of 30 seconds. The wait is only a convenience for fast jobs; longer work continues durably and should be polled by job ID.

MCP waits for up to 55 seconds by default. Work that remains active returns a pending job ID for later retrieval.

## Capability timeouts

Each capability publishes a `timeout_ms` limit. That execution deadline is distinct from the HTTP wait window. Ending an HTTP wait does not mean the worker timed out, and increasing `Prefer: wait` cannot extend the capability.s published execution timeout.

## Rate limits

Rate limits apply to authenticated API and MCP traffic. A limited request returns HTTP `429` with both `Retry-After` and `retry_after_ms`. Respect the advertised delay rather than using a fixed aggressive retry interval.

Each module declares one fixed positive credits_per_request value. Every capability in that module is published and charged at that fixed cost.

When credits are charged

Credits are charged once when a logical job completes successfully.

The completed response also reports billing.settlement. A zero charge with a positive published rate is intentional when settlement is included_subscription or out_of_band_contract; it is not evidence that the capability is free. zero_charge_requires_review indicates an unexpected settlement state; contact Upscrape support if it appears in a response.

The following do not add another capability charge:

a pending response;
polling a job;
internal worker retries;
a failed job;
an idempotent replay of the same logical request.

Credit reservations prevent concurrent requests from overspending the same remaining balance. A zero balance blocks new execution.

Find the cost

The public platform page displays the credit cost next to every capability. The value comes from the same published capability contract used during execution, not from page-specific copy.

Wait limits

REST accepts Prefer: wait=N with a maximum of 30 seconds. The wait is only a convenience for fast jobs; longer work continues durably and should be polled by job ID.

MCP waits for up to 55 seconds by default. Work that remains active returns a pending job ID for later retrieval.

Capability timeouts

Each capability publishes a timeout_ms limit. That execution deadline is distinct from the HTTP wait window. Ending an HTTP wait does not mean the worker timed out, and increasing Prefer: wait cannot extend the capability.s published execution timeout.

Rate limits

Rate limits apply to authenticated API and MCP traffic. A limited request returns HTTP 429 with both Retry-After and retry_after_ms. Respect the advertised delay rather than using a fixed aggressive retry interval.