Safe retries

A connection can drop after you send a request but before the answer arrives. Did the call run? An Idempotency-Key makes the question harmless: send the request again with the same key and you get the first job back, never a second one, and never a second charge.

Send a key

Add the header to POST /execute, with a value that names this one piece of work:

Idempotency-Key: weekly-coffee-sf-2026-10-16

• Use a value you can make again for the same work, such as your own record ID plus a date, or a random UUID you store with your task.

• Up to 255 characters.

• Keys belong to your account, so two accounts never collide.

What happens on a repeat

{  "error": {    "code": "idempotency_conflict",    "message": "idempotency key has already been used for a different request"  }}

A conflict means one key was given to two different pieces of work. Fix how you make keys rather than dropping the key.

Retry safely

1. Make or load the key for this piece of work.

2. Send POST /execute with it.

3. If you don't know whether the request arrived, send exactly the same request with the same key.

4. Once you have a job_id, fetch the job with GET /jobs/{id} until it finishes. Don't send the request again.

Over MCP

The MCP tool upscrape_execute takes an operation_key that works the same way. Without one, a repeat of the same call within about 15 minutes, with the same request ID and arguments, returns the first job; after that it starts a new one.