Run an endpoint

POST /execute runs any endpoint with its input.

POST /execute runs any endpoint. You send the endpoint's ID and its input; you get the job back, finished or still running.

The request

HTTP

POST https://data.upscrape.com/executeAuthorization: Bearer UPSCRAPE_API_KEYContent-Type: application/jsonPrefer: wait=30Idempotency-Key: 6f1c2d4e-weekly-coffee-sf

JSON

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

Part	Required	What it does
`capability`	Yes	The endpoint's ID. Each endpoint's reference page gives it.
`input`	Yes	The endpoint's fields, as its reference page lists them.
`max_credits`	No	The most this call may cost, as a whole number. The `X-Max-Credits` header does the same; the body wins if both are sent.
`Prefer: wait=N`	No	Wait up to `N` seconds for the result, at most 30.
`Idempotency-Key`	No	Makes a retry return the same job instead of starting a second one. See Safe retries.

Every address also works under /v1, such as POST https://data.upscrape.com/v1/execute. Use whichever you prefer; both stay.

Waiting for the result

With Prefer: wait=30, the response waits up to 30 seconds:

Finished in time: HTTP 200 and the result.
Still running: HTTP 202 and the job, with poll_url and poll_after_ms. The job keeps running; fetch it at poll_url, as Jobs and results shows.

Without Prefer, the call answers 202 at once and runs in the background. Use this when you send many calls and collect the results later.

A finished call

JSON

{  "job_id": "d7ef67f5-8cb8-4989-8b55-8ba67a1aab4f",  "state": "completed",  "success": true,  "platform": "googlemaps",  "capability": "googlemaps.search",  "results": [    {      "data": {"items": ["…"], "summary": {"total_items": 5, "has_more": true}}    }  ],  "billing": {"credits_charged": 1},  "started_at": "2026-10-16T19:29:37.179829Z",  "completed_at": "2026-10-16T19:29:37.956810Z"}

The endpoint's data is in results[0].data, shaped as its reference page shows. billing.credits_charged is what the call cost. The response carries a few more fields, such as stats with timings; read the ones you need by name.

Setting a ceiling

If the endpoint's price for your input is above max_credits, the call is refused with HTTP 422 and credit_limit_exceeded before anything runs. A part-credit price counts as the next whole credit for this check, so max_credits: 1 allows a 0.25-credit call. The ceiling never changes the price you pay.

When it goes wrong

The request is wrong, such as a missing field or an unknown endpoint ID: HTTP 422 with invalid_input, and error.fields names each problem. Fix the request; sending it again unchanged fails the same way.
The endpoint can't run right now: HTTP 503 with temporarily_unavailable, and no job is created. Try again later.
The job fails while you wait: the response has state: "failed", a 4xx or 5xx status that fits the failure, and an error.code. It is never a 200.

Errors and retries lists every code and which ones to retry.

What you pay

The endpoint's price for your input, once, when the job completes. Checking on a job, the retries Upscrape makes for you, a failed job and a repeat with the same Idempotency-Key cost nothing. Credits and limits has the details.

Something missing or unclear? Ask the team that builds the endpoints.