REST API

Credits and limits

Understand charging, rate limits, waits, and timeouts.

Each capability publishes its `credits_per_request` cost. A capability whose price depends on its input publishes a range instead, shown as `N-M credits / request`; the price for the submitted input is what is charged. Check the applicable price before submitting a request.

A price can be a part of a credit, such as `0.25 credits / request`. Credits are bought and held in whole numbers; each part-credit request is charged exactly, and your balance shows what it has used, for example `9.75` after one `0.25` request from `10`. Whole credits come off the balance each time the parts add up to one. A completed job's `billing.credits_charged` and `billing.credits_per_unit` report the exact amounts, so they can be decimals.

## 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;
- automatic 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.

## Cap the cost of a request

`POST /execute` accepts an optional `max_credits` body field or `X-Max-Credits` header. A job whose published price is higher is refused with `credit_limit_exceeded` before it is accepted, so nothing is charged. MCP tools accept the same ceiling as `max_credits`. The ceiling is a whole number; a part-credit price counts as the next whole credit for this check, so `max_credits: 1` accepts a `0.25`-credit request.

## 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 request timed out, and increasing `Prefer: wait` cannot extend the capability's published execution timeout.

## Requests at a time

A prepaid account runs up to 3 requests at a time. Buying a credit pack raises that for good: the $49 pack to 5, the $149 pack to 10 and the $499 pack to 20. Requests beyond the limit wait in line and start as earlier ones finish; with `Prefer: wait` they may come back as `202` with a `poll_url`. Custom plans set their own limit.

## Rate limits

Rate limits apply to authenticated API and MCP traffic, per key and across all of an account's keys together. An account holds at most 25 active API keys. 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 capability publishes its credits_per_request cost. A capability whose price depends on its input publishes a range instead, shown as N-M credits / request; the price for the submitted input is what is charged. Check the applicable price before submitting a request.

A price can be a part of a credit, such as 0.25 credits / request. Credits are bought and held in whole numbers; each part-credit request is charged exactly, and your balance shows what it has used, for example 9.75 after one 0.25 request from 10. Whole credits come off the balance each time the parts add up to one. A completed job's billing.credits_charged and billing.credits_per_unit report the exact amounts, so they can be decimals.

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;
automatic 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.

Cap the cost of a request

POST /execute accepts an optional max_credits body field or X-Max-Credits header. A job whose published price is higher is refused with credit_limit_exceeded before it is accepted, so nothing is charged. MCP tools accept the same ceiling as max_credits. The ceiling is a whole number; a part-credit price counts as the next whole credit for this check, so max_credits: 1 accepts a 0.25-credit request.

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 request timed out, and increasing Prefer: wait cannot extend the capability's published execution timeout.

Requests at a time

A prepaid account runs up to 3 requests at a time. Buying a credit pack raises that for good: the $49 pack to 5, the $149 pack to 10 and the $499 pack to 20. Requests beyond the limit wait in line and start as earlier ones finish; with Prefer: wait they may come back as 202 with a poll_url. Custom plans set their own limit.

Rate limits

Rate limits apply to authenticated API and MCP traffic, per key and across all of an account's keys together. An account holds at most 25 active API keys. 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.

Credit prices and plans: Upscrape pricing