Durable (async) requests and request history
Add Prefer: respond-async to POST /v1/run/{endpoint_id} to get 202 Accepted at once, or Prefer: wait=N (max 90 s) to wait up to N seconds first. Without Prefer the call is synchronous.
A 202 carries Location: /v1/requests/{request_id} and Retry-After, and a snapshot:
{"ok": true, "request_id": "req_…", "endpoint": "seo.audit", "status": "queued",
"created_at": "…", "expires_at": "…", "retry_after_seconds": 2}
Poll GET /v1/requests/{request_id}. status is queued, running, succeeded or failed. A succeeded snapshot has the normal run envelope in result; a failed one has error.code. Polling is free and never re-runs the paid call. Request ids are scoped to the wallet; others get 404.
With an Idempotency-Key, re-submitting while the job is active returns the same snapshot; after it succeeds the stored result is replayed.
A paid run is executed at most once. If the server restarts mid-job, the job is marked failed (interrupted) and the charge is not kept.
History
GET /v1/requests?limit=20&before=<cursor>— newest first across every key on the wallet:request_id,endpoint,key_prefix,status,http_status,cost_usd,items,latency_ms,input,created_at,error. Follownext_cursor(pass it asbefore);nullmeans no more pages.GET /v1/results/{request_id}— re-read a stored result for free, with the samefields/max_items/summarycontrols.
Retention
Successful output stays readable for 24 hours, then for the wallet's retention setting (0, 3 or 7 days; default 3): POST /v1/account/settings {"retention_days": 7}. After that result_expired: true (history metadata stays).
Plain Markdown for agents: /docs/durable-requests.md · index: llms.txt