How a call works

Every endpoint, on every platform and for any website, works the same way. Learn it once here and the rest of the docs are details.

One request for every endpoint

You send one request to POST https://data.upscrape.com/execute with your API key. The body names the endpoint and gives its input:

{  "capability": "googlemaps.search",  "input": {"query": "coffee shops", "location": "San Francisco, CA", "limit": 5}}

An AI agent connected over MCP makes the same call through the upscrape_execute tool, with the same endpoints and the same prices.

The price comes first

Every endpoint publishes its price in credits before you call it: on its reference page, in the catalog, and to an agent before it runs anything. Most endpoints cost 1 credit. A few charge by what they return and publish a range, such as 1 to 9 credits.

To make sure a call never costs more than you expect, send max_credits. If the endpoint's price for your input could be higher, the call is refused with HTTP 422 and credit_limit_exceeded before anything runs.

Every call is a job

Each call becomes a job with a job_id. A job is queued, then running, and ends completed or failed. A job that hit a passing problem shows retrying while Upscrape tries again for you.

How you get the result depends on how long you are willing to wait:

• Wait for it. Send the header Prefer: wait=30 and the response waits up to 30 seconds. If the job finishes in time, you get HTTP 200 with the result. Most calls finish in a few seconds.

• Check back. If the job is still running when the wait ends, or you sent no Prefer header, you get HTTP 202 with a poll_url. Fetch it after poll_after_ms until the job has finished; Jobs and results shows how.

Never send the same request again because it is slow: that starts a second job. To retry safely after a dropped connection, send an Idempotency-Key.

What you pay for

A call is charged once, when its job completes, at the price it published. Everything else is free:

• a call that fails;

• checking on a job;

• a retry with the same Idempotency-Key, which returns the first job;

• asking for the same data again soon after, which is answered from the result you already paid for.

billing.credits_charged on every finished job says what it cost. Credits and limits covers balances and how many calls run at once.

Where the data is

A finished job looks the same for every endpoint. The endpoint's own data is in results[0].data:

{  "job_id": "d7ef67f5-8cb8-4989-8b55-8ba67a1aab4f",  "state": "completed",  "success": true,  "capability": "googlemaps.search",  "results": [    {"data": {"items": ["…"], "summary": {"total_items": 5, "has_more": true}}}  ],  "billing": {"credits_charged": 1}}

Each endpoint's reference page lists every field its data holds, with a real response. A failed job has success: false and an error.code instead of data; Errors and retries lists every code.

Next

• Run an endpoint: every option of POST /execute.

• Credits and limits: balances, prices and concurrency.

• Platforms and endpoints: every endpoint's ID, input and price.