Only on GET /v1/runs/{id}. The list, create and cancel responses do not include it. It is also missing when your credit history could not be read: read the run again.
Set on every queued run read with GET /v1/runs/{id}, null once the run has left the queue. On the 202 of POST /v1/runs, queue can be null or already out of date: GET /v1/runs/{id} is the reference.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Retriever API","colors":{"primary":"#4F46E5"},"seo":{"indexing":"navigable"},"contextual":{"options":["copy","view","chatgpt","claude","perplexity","mcp","cursor","vscode","download-spec"],"display":"header"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"retriever-3987567e","hasAudioNarration":false,"actualSubdomain":"retriever-3987567e","customDomains":["docs.retriever.run"],"gitSource":{"type":"github","owner":"yonsy7","repo":"agentic-list-building","deployBranch":"master","contentDirectory":"docs/api/public","isPrivate":true,"mountPath":"","label":""},"chroma":{"latestBuiltDeploymentHistoryId":"6ad1c49dbb2721f7e342dd4e","collectionId":"6398e8db-5d50-4b27-8556-82d610a8d2e6","liveDeploymentHistoryId":"6ad1c49dbb2721f7e342dd4e","schemaVersion":"v3"},"entitlements":{"AI_CHAT":{"status":"DISABLED"},"WEB_MCP":{"status":"DISABLED"},"NARRATION":{"status":"DISABLED"}},"buildId":"6ad1f6a7576d41a597562ea7","clientVersion":"0.0.4043","searchFilterCounts":[{"language":"default","tag":"API reference","count":32},{"language":"default","tag":"Guides","count":18},{"language":"default","tag":"Runs","count":9},{"language":"default","tag":"Services","count":9},{"language":"default","tag":"Recipes","count":8},{"language":"default","tag":"Concepts","count":6},{"language":"default","tag":"Go","count":4},{"language":"default","tag":"Workspaces","count":4},{"language":"default","tag":"Exclusions","count":3},{"language":"default","tag":"Get started","count":2}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/runs/cancel-run","slug":"/api-reference/runs/cancel-run","pageMetadata":{"title":"Request cancellation","description":"Sets `cancellation_requested: true`. The worker stops at the next\nheartbeat. Changes already made to tables are kept.\n","deprecated":null,"version":null,"sidebarTitle":"Cancel run","openapi":"/openapi.yaml post /v1/runs/{id}/cancel","href":"/api-reference/runs/cancel-run","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_components.p, {\n children: [\"Sets \", _jsx(_components.code, {\n children: \"cancellation_requested: true\"\n }), \". The worker stops at the next\\nheartbeat. Changes already made to tables are kept.\"]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Request cancellation","description":"Sets `cancellation_requested: true`. The worker stops at the next\nheartbeat. Changes already made to tables are kept.\n","deprecated":null,"version":null,"sidebarTitle":"Cancel run","openapi":"/openapi.yaml post /v1/runs/{id}/cancel","href":"/api-reference/runs/cancel-run","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"tags":["Runs"],"operationId":"cancelRun","x-mint":{"href":"/api-reference/runs/cancel-run"},"summary":"Request cancellation","description":"Sets `cancellation_requested: true`. The worker stops at the next\nheartbeat. Changes already made to tables are kept.\n","parameters":["b02f9d88-880e-4a2c-8cde-e1bf3d517771"],"responses":{"200":"6e68a699-c7b1-4dc5-8119-0e4c1bf75968","401":"a916352a-430f-4eb9-8e96-b14977211674","404":"825b30dd-f592-4761-8a83-c5df5247666b","413":"07dc496b-2ffe-46af-a7ef-7326e17131d4","429":"7d8810c8-aca6-441a-8b2b-d370112ea6a3"},"method":"post","type":"path","servers":["f1f50859-a682-49e6-8d68-df5f1384c422","a55f1192-b1ce-44b1-9592-9a845f4f9936"],"security":["5359af61-e76c-4569-9ee1-184c3a970601"],"path":"/v1/runs/{id}/cancel","baseUrlOptions":["https://api.retriever.run","http://localhost:4320"],"title":"Request cancellation","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"b02f9d88-880e-4a2c-8cde-e1bf3d517771":{"name":"id","in":"path","required":true,"schema":{"type":"string","isRequired":true,"uniqueKey":"","typeLabel":"string"},"example":"run_001"}},"responses":{"6e68a699-c7b1-4dc5-8119-0e4c1bf75968":{"description":"Run updated.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","uniqueKey":"id","typeLabel":"string"},"workspace_id":{"type":"string","uniqueKey":"workspace_id","typeLabel":"string"},"conversation_id":{"type":"string","uniqueKey":"conversation_id","typeLabel":"string"},"status":{"type":"string","enum":["queued","running","recovering","completed","failed","cancelled"],"uniqueKey":"status","typeLabel":"enum\u003cstring>"},"message":{"oneOf":[{"type":"string","description":"Agent's final text.","uniqueKey":"message.oneOf.0","typeLabel":"string"},{"type":"null","description":"Agent's final text.","uniqueKey":"message.oneOf.1","typeLabel":"null"}],"uniqueKey":"message","typeLabel":"string | null"},"artifacts":{"type":"array","description":"Tables created or updated by the run (live state).","items":{"type":"object","properties":{"type":{"const":"table","uniqueKey":"artifacts.items.[INDEX].type","typeLabel":"any"},"id":{"type":"string","uniqueKey":"artifacts.items.[INDEX].id","typeLabel":"string"},"name":{"type":"string","uniqueKey":"artifacts.items.[INDEX].name","typeLabel":"string"},"effect":{"type":"string","enum":["created","updated"],"uniqueKey":"artifacts.items.[INDEX].effect","typeLabel":"enum\u003cstring>"},"links":{"type":"object","properties":{"self":{"type":"string","uniqueKey":"artifacts.items.[INDEX].links.self","typeLabel":"string"},"rows":{"type":"string","uniqueKey":"artifacts.items.[INDEX].links.rows","typeLabel":"string"}},"uniqueKey":"artifacts.items.[INDEX].links","typeLabel":"object"}},"uniqueKey":"artifacts.items.[INDEX]","typeLabel":"object"},"uniqueKey":"artifacts","typeLabel":"object[]"},"last_heartbeat_at":{"oneOf":[{"type":"string","format":"date-time","uniqueKey":"last_heartbeat_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","uniqueKey":"last_heartbeat_at.oneOf.1","typeLabel":"null"}],"uniqueKey":"last_heartbeat_at","typeLabel":"string\u003cdate-time> | null"},"progress":{"type":"object","properties":{"phase":{"oneOf":[{"type":"string","uniqueKey":"progress.phase.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"progress.phase.oneOf.1","typeLabel":"null"}],"uniqueKey":"progress.phase","typeLabel":"string | null"},"updated_at":{"type":"string","uniqueKey":"progress.updated_at","typeLabel":"string"}},"uniqueKey":"progress","typeLabel":"object"},"output":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["json","tables"],"uniqueKey":"output.oneOf.0.type","typeLabel":"enum\u003cstring>"},"links":{"type":"object","properties":{"self":{"type":"string","uniqueKey":"output.oneOf.0.links.self","typeLabel":"string"}},"uniqueKey":"output.oneOf.0.links","typeLabel":"object"}},"uniqueKey":"output.oneOf.0","typeLabel":"object"},{"type":"null","properties":{"type":{"type":"string","enum":["json","tables"]},"links":{"type":"object","properties":{"self":{"type":"string"}}}},"uniqueKey":"output.oneOf.1","typeLabel":"null"}],"uniqueKey":"output","typeLabel":"object | null"},"error":{"oneOf":[{"type":"object","properties":{"code":{"type":"string","uniqueKey":"error.oneOf.0.code","typeLabel":"string"},"message":{"type":"string","uniqueKey":"error.oneOf.0.message","typeLabel":"string"}},"uniqueKey":"error.oneOf.0","typeLabel":"object"},{"type":"null","properties":{"code":{"type":"string"},"message":{"type":"string"}},"uniqueKey":"error.oneOf.1","typeLabel":"null"}],"uniqueKey":"error","typeLabel":"object | null"},"credits":{"type":"object","description":"Only on `GET /v1/runs/{id}`. The list, create and cancel responses do not include it. It is also missing when your credit history could not be read: read the run again.","properties":{"charged":{"type":"number","description":"Credits the run was charged so far: the services and data sources it called, including the cells of the columns it launched (AI columns included), the research agent that fills a column row by row, browser sessions, and AI-written sequence messages written during the run (the first message of each lead it enrolls in an active sequence; every other AI sequence message, including those of a draft sequence the agent activates, is written when its step is due and is not charged on the run). The main agent's own model calls are not billed. It grows while the run is active, keeps growing after the run ends while cells of the columns it launched are still running, can grow after the end when a charge is recorded late (most often a call cut by a timeout, or aborted by a Stop or a cancel, whose answer landed just after the cut). A failed or cancelled run shows what it used so far: on a Stop or a cancel, running cells go back to their previous value at once, but a call they already sent can still be billed on the run. No field marks the amount as final. Read the rows of the run's tables (`artifacts`, `GET /v1/tables/{id}/rows?include_hidden=true`: hidden columns run and bill too) until no cell has `status` `running`, then read the run again later. A cell that reads `failed` may still be retried automatically, up to two times, depending on its service and on why it failed. While it waits for its retry it reads `failed`, and nothing in the API tells a failed cell that will be retried from a final one. A retried cell waits its turn in the queue, which can take more than a few minutes, and the amount grows again if the retry gets an answer. Treat the amount as provisional until it has stopped changing over a longer window. Cells started by other activity on those tables count as running too.","uniqueKey":"credits.charged","typeLabel":"number"}},"uniqueKey":"credits","typeLabel":"object"},"created_at":{"type":"string","format":"date-time","uniqueKey":"created_at","typeLabel":"string\u003cdate-time>"},"updated_at":{"type":"string","format":"date-time","uniqueKey":"updated_at","typeLabel":"string\u003cdate-time>"},"started_at":{"oneOf":[{"type":"string","format":"date-time","description":"Null while the run is `queued`. The maximum run duration counts from here.","uniqueKey":"started_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","description":"Null while the run is `queued`. The maximum run duration counts from here.","uniqueKey":"started_at.oneOf.1","typeLabel":"null"}],"uniqueKey":"started_at","typeLabel":"string\u003cdate-time> | null"},"completed_at":{"oneOf":[{"type":"string","format":"date-time","uniqueKey":"completed_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","uniqueKey":"completed_at.oneOf.1","typeLabel":"null"}],"uniqueKey":"completed_at","typeLabel":"string\u003cdate-time> | null"},"cancellation_requested":{"type":"boolean","uniqueKey":"cancellation_requested","typeLabel":"boolean"},"queue":{"oneOf":[{"type":"object","description":"Set on every `queued` run read with `GET /v1/runs/{id}`, `null` once the run has left the queue. On the `202` of `POST /v1/runs`, `queue` can be `null` or already out of date: `GET /v1/runs/{id}` is the reference.","required":["reason","active_runs","limit","ahead"],"properties":{"reason":{"type":"string","enum":["organization_limit","waiting_for_worker"],"description":"`organization_limit`: the organization's slots are taken, by executing runs and older queued runs; the run starts on its own as runs end. `waiting_for_worker`: a slot is free; a worker usually takes the run within seconds, longer during a deploy or when many organizations have runs waiting.","isRequired":true,"uniqueKey":"queue.oneOf.0.reason","typeLabel":"enum\u003cstring>"},"active_runs":{"type":"integer","description":"Runs of the organization `running` or `recovering` now.","isRequired":true,"uniqueKey":"queue.oneOf.0.active_runs","typeLabel":"integer"},"limit":{"type":"integer","description":"Runs one organization executes at the same time (5 by default).","isRequired":true,"uniqueKey":"queue.oneOf.0.limit","typeLabel":"integer"},"ahead":{"type":"integer","description":"Older queued runs of the organization. They start before this one.","isRequired":true,"uniqueKey":"queue.oneOf.0.ahead","typeLabel":"integer"}},"uniqueKey":"queue.oneOf.0","typeLabel":"object"},{"type":"null","description":"Set on every `queued` run read with `GET /v1/runs/{id}`, `null` once the run has left the queue. On the `202` of `POST /v1/runs`, `queue` can be `null` or already out of date: `GET /v1/runs/{id}` is the reference.","required":["reason","active_runs","limit","ahead"],"properties":{"reason":{"type":"string","enum":["organization_limit","waiting_for_worker"],"description":"`organization_limit`: the organization's slots are taken, by executing runs and older queued runs; the run starts on its own as runs end. `waiting_for_worker`: a slot is free; a worker usually takes the run within seconds, longer during a deploy or when many organizations have runs waiting."},"active_runs":{"type":"integer","description":"Runs of the organization `running` or `recovering` now."},"limit":{"type":"integer","description":"Runs one organization executes at the same time (5 by default)."},"ahead":{"type":"integer","description":"Older queued runs of the organization. They start before this one."}},"uniqueKey":"queue.oneOf.1","typeLabel":"null"}],"uniqueKey":"queue","typeLabel":"object | null"},"links":{"type":"object","properties":{"self":{"type":"string","uniqueKey":"links.self","typeLabel":"string"},"app":{"type":"string","description":"Opens the run conversation and its tables in the Retriever app (session required).","uniqueKey":"links.app","typeLabel":"string"}},"uniqueKey":"links","typeLabel":"object"}},"example":{"id":"run_001","workspace_id":"ws_001","conversation_id":"conv_001","status":"completed","message":"I created the Fintechs FR table with 30 companies.","artifacts":[{"type":"table","id":"tbl_001","name":"Fintechs FR","effect":"created","links":{"self":"/v1/tables/tbl_001","rows":"/v1/tables/tbl_001/rows"}}],"output":null,"error":null,"cancellation_requested":false,"queue":null,"links":{"self":"/v1/runs/run_001","app":"https://app.retriever.run/app/workspaces/ws_001/conversations/conv_001"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"id":"run_001","workspace_id":"ws_001","conversation_id":"conv_001","status":"completed","message":"I created the Fintechs FR table with 30 companies.","artifacts":[{"type":"table","id":"tbl_001","name":"Fintechs FR","effect":"created","links":{"self":"/v1/tables/tbl_001","rows":"/v1/tables/tbl_001/rows"}}],"output":null,"error":null,"cancellation_requested":false,"queue":null,"links":{"self":"/v1/runs/run_001","app":"https://app.retriever.run/app/workspaces/ws_001/conversations/conv_001"}}}},"exampleType":"generated"}},"exampleType":"generated"},"a916352a-430f-4eb9-8e96-b14977211674":{"description":"`not_authenticated`: missing header, malformed (expected `Bearer \u003ckey>`), revoked or unknown key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable code; use in your application.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable explanation. May change.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"details":{"description":"Optional details (e.g. list of invalid fields).","uniqueKey":"error.details","typeLabel":"any"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"not_authenticated","message":"A valid API key is required."}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"not_authenticated","message":"A valid API key is required."}}}},"exampleType":"examples"}},"exampleType":"examples"},"825b30dd-f592-4761-8a83-c5df5247666b":{"description":"`run_not_found`: unknown id, or another organization's run. A Go job (`/v1/go/runs`) is also not found for another user of your organization.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable code; use in your application.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable explanation. May change.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"details":{"description":"Optional details (e.g. list of invalid fields).","uniqueKey":"error.details","typeLabel":"any"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"run_not_found","message":"Run not found."}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"run_not_found","message":"Run not found."}}}},"exampleType":"examples"}},"exampleType":"examples"},"07dc496b-2ffe-46af-a7ef-7326e17131d4":{"description":"`body_too_large`: the request body is over 10 MiB (10,485,760 bytes). Do not retry the same body: send less data per request.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable code; use in your application.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable explanation. May change.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"details":{"description":"Optional details (e.g. list of invalid fields).","uniqueKey":"error.details","typeLabel":"any"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"body_too_large","message":"The request body exceeds the 10 MiB limit (10485760 bytes)."}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"body_too_large","message":"The request body exceeds the 10 MiB limit (10485760 bytes)."}}}},"exampleType":"examples"}},"exampleType":"examples"},"7d8810c8-aca6-441a-8b2b-d370112ea6a3":{"description":"`rate_limited`: wait `Retry-After` seconds, then retry.","headers":{"Retry-After":{"schema":{"type":"integer"}},"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Window budget."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining requests."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until reset."}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable code; use in your application.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","description":"Human-readable explanation. May change.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"details":{"description":"Optional details (e.g. list of invalid fields).","uniqueKey":"error.details","typeLabel":"any"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"rate_limited","message":"Rate limit exceeded. Retry in 12 s."}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"rate_limited","message":"Rate limit exceeded. Retry in 12 s."}}}},"exampleType":"examples"}},"exampleType":"examples"}},"security":{"5359af61-e76c-4569-9ee1-184c3a970601":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key `ret_live_…` created in Settings → API keys.","scopes":[],"schemeName":"bearerAuth"}}},"servers":{"f1f50859-a682-49e6-8d68-df5f1384c422":{"url":"https://api.retriever.run","description":"Production"},"a55f1192-b1ce-44b1-9592-9a845f4f9936":{"url":"http://localhost:4320","description":"Local app-server"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","scheme":"bearer","description":"API key `ret_live_…` created in Settings → API keys.","scopes":[],"schemeName":"bearerAuth"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"API key `ret_live_…` created in Settings → API keys.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"bearerAuth","name":"Authorization"}],"title":"bearerAuth"}]},"originalFileLocation":"openapi.yaml"},"subdomain":"retriever-3987567e","siteName":"Retriever API","title":"Request cancellation - Retriever API","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-16T06:30:58.248Z","originalFileLocation":"api-reference/runs/cancel-run.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Sets cancellation_requested: true. The worker stops at the next heartbeat. Changes already made to tables are kept.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Retriever API\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/retriever-3987567e/_generated/favicon/apple-touch-icon.png?v=3\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/retriever-3987567e/_generated/favicon/favicon-32x32.png?v=3\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/retriever-3987567e/_generated/favicon/favicon-16x16.png?v=3\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"https://mintlify.s3.us-west-1.amazonaws.com/retriever-3987567e/_generated/favicon/favicon.ico?v=3\">\u003cmeta data-mint-head property=\"og:title\" content=\"Request cancellation - Retriever API\">\u003cmeta data-mint-head property=\"og:description\" content=\"Sets cancellation_requested: true. The worker stops at the next heartbeat. Changes already made to tables are kept.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Retriever API\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.retriever.run/api-reference/runs/cancel-run\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://retriever-3987567e.mintlify.app/_mintlify/api/og/v2?division=Runs\u0026amp;title=Request+cancellation\u0026amp;description=Sets+%60cancellation_requested%3A+true%60.+The+worker+stops+at+the+next%0Aheartbeat.+Changes+already+made+to+tables+are+kept.%0A\u0026amp;theme=4c917abfdccf5db373a73b47\u0026amp;signature=6b58faff1aba7c01d3e09ca2df3bbd2facb2736b698b58c99f44af57be0eb9c6\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Request cancellation - Retriever API\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Sets cancellation_requested: true. The worker stops at the next heartbeat. Changes already made to tables are kept.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://retriever-3987567e.mintlify.app/_mintlify/api/og/v2?division=Runs\u0026amp;title=Request+cancellation\u0026amp;description=Sets+%60cancellation_requested%3A+true%60.+The+worker+stops+at+the+next%0Aheartbeat.+Changes+already+made+to+tables+are+kept.%0A\u0026amp;theme=4c917abfdccf5db373a73b47\u0026amp;signature=6b58faff1aba7c01d3e09ca2df3bbd2facb2736b698b58c99f44af57be0eb9c6\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"https://mintlify.s3.us-west-1.amazonaws.com/retriever-3987567e/_generated/favicon/browserconfig.xml?v=3\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Retriever API\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#4F46E5\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.retriever.run/api-reference/runs/cancel-run\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/runs/cancel-run.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.retriever.run/#organization\",\"name\":\"Retriever API\",\"url\":\"https://docs.retriever.run\"},{\"@type\":\"WebSite\",\"@id\":\"https://docs.retriever.run#website\",\"name\":\"Retriever API\",\"url\":\"https://docs.retriever.run\",\"publisher\":{\"@id\":\"https://docs.retriever.run/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.retriever.run/api-reference/runs/cancel-run#webpage\",\"url\":\"https://docs.retriever.run/api-reference/runs/cancel-run\",\"name\":\"Request cancellation\",\"description\":\"Sets cancellation_requested: true. The worker stops at the next heartbeat. Changes already made to tables are kept.\",\"dateModified\":\"2026-10-16T06:30:58.248Z\",\"isPartOf\":{\"@id\":\"https://docs.retriever.run#website\"},\"breadcrumb\":{\"@id\":\"https://docs.retriever.run/api-reference/runs/cancel-run#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.retriever.run/api-reference/runs/cancel-run#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Runs\",\"item\":\"https://docs.retriever.run/api-reference/runs/list-runs\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Request cancellation\",\"item\":\"https://docs.retriever.run/api-reference/runs/cancel-run\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.retriever.run/api-reference/runs/cancel-run#apireference\",\"headline\":\"Request cancellation\",\"name\":\"Request cancellation\",\"description\":\"Sets cancellation_requested: true. The worker stops at the next heartbeat. Changes already made to tables are kept.\",\"url\":\"https://docs.retriever.run/api-reference/runs/cancel-run\",\"mainEntityOfPage\":{\"@id\":\"https://docs.retriever.run/api-reference/runs/cancel-run#webpage\"},\"dateModified\":\"2026-10-16T06:30:58.248Z\",\"publisher\":{\"@id\":\"https://docs.retriever.run/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.retriever.run#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Retriever API\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Retriever API","nav":{"global":null,"tabs":[{"tab":"Guides","pages":[{"title":"Guides","href":""}]},{"tab":"API reference","groups":[{"group":"Runs","pages":[{"title":"List runs","deprecated":null,"version":null,"sidebarTitle":"List runs","openapi":"/openapi.yaml get /v1/runs","href":"/api-reference/runs/list-runs"},{"title":"Start a run","deprecated":null,"version":null,"sidebarTitle":"Create run","openapi":"/openapi.yaml post /v1/runs","href":"/api-reference/runs/create-run"},{"title":"Get run status","description":"Poll until a terminal status (`completed`, `failed`, `cancelled`).\nHonor `Retry-After` (15 s for an active run). Send `If-None-Match` with\nthe `ETag` from a prior read to get `304` when nothing changed.\n\nOnly this read returns `credits.charged`, the credits the run was\ncharged so far. The list, create and cancel responses leave it out.\n","deprecated":null,"version":null,"sidebarTitle":"Get run","openapi":"/openapi.yaml get /v1/runs/{id}","href":"/api-reference/runs/get-run"},{"title":"Request cancellation","deprecated":null,"version":null,"sidebarTitle":"Cancel run","openapi":"/openapi.yaml post /v1/runs/{id}/cancel","href":"/api-reference/runs/cancel-run"},{"title":"Get published output","description":"Available only if the run was created with `output` and has finished.","deprecated":null,"version":null,"sidebarTitle":"Get run output","openapi":"/openapi.yaml get /v1/runs/{id}/output","href":"/api-reference/runs/get-run-output"},{"title":"Frozen table metadata","deprecated":null,"version":null,"sidebarTitle":"Get output table","openapi":"/openapi.yaml get /v1/runs/{id}/output/tables/{key}","href":"/api-reference/runs/get-output-table"},{"title":"Frozen table rows","deprecated":null,"version":null,"sidebarTitle":"List output table rows","openapi":"/openapi.yaml get /v1/runs/{id}/output/tables/{key}/rows","href":"/api-reference/runs/list-output-table-rows"},{"title":"Create a CSV or JSON export of a frozen table","deprecated":null,"version":null,"sidebarTitle":"Create export","openapi":"/openapi.yaml post /v1/runs/{id}/exports","href":"/api-reference/runs/create-export"},{"title":"Download an export","deprecated":null,"version":null,"sidebarTitle":"Download export","openapi":"/openapi.yaml get /v1/runs/{id}/exports/{exportId}","href":"/api-reference/runs/download-export"}]},{"group":"Tables","pages":[{"title":"Live table metadata","deprecated":null,"version":null,"sidebarTitle":"Get table","openapi":"/openapi.yaml get /v1/tables/{id}","href":"/api-reference/tables/get-table"},{"title":"Live table rows","deprecated":null,"version":null,"sidebarTitle":"List table rows","openapi":"/openapi.yaml get /v1/tables/{id}/rows","href":"/api-reference/tables/list-table-rows"}]},{"group":"Workspaces","pages":[{"title":"List workspaces","deprecated":null,"version":null,"sidebarTitle":"List workspaces","openapi":"/openapi.yaml get /v1/workspaces","href":"/api-reference/workspaces/list-workspaces"},{"title":"Create a workspace","deprecated":null,"version":null,"sidebarTitle":"Create workspace","openapi":"/openapi.yaml post /v1/workspaces","href":"/api-reference/workspaces/create-workspace"},{"title":"List non-archived tables","deprecated":null,"version":null,"sidebarTitle":"List workspace tables","openapi":"/openapi.yaml get /v1/workspaces/{id}/tables","href":"/api-reference/workspaces/list-workspace-tables"},{"title":"Import a table (columns + JSON rows)","deprecated":null,"version":null,"sidebarTitle":"Import table","openapi":"/openapi.yaml post /v1/workspaces/{id}/tables","href":"/api-reference/workspaces/import-table"}]},{"group":"Exclusions","pages":[{"title":"List an exclusion list","deprecated":null,"version":null,"sidebarTitle":"List exclusions","openapi":"/openapi.yaml get /v1/exclusions/{kind}","href":"/api-reference/exclusions/list-exclusions"},{"title":"Add values (upsert)","deprecated":null,"version":null,"sidebarTitle":"Add exclusions","openapi":"/openapi.yaml post /v1/exclusions/{kind}","href":"/api-reference/exclusions/add-exclusions"},{"title":"Remove values","deprecated":null,"version":null,"sidebarTitle":"Remove exclusions","openapi":"/openapi.yaml post /v1/exclusions/{kind}/remove","href":"/api-reference/exclusions/remove-exclusions"}]},{"group":"Go","pages":[{"title":"Synchronous structured research","deprecated":null,"version":null,"sidebarTitle":"Run sync","openapi":"/openapi.yaml post /v1/go/run","href":"/api-reference/go/run-sync"},{"title":"Asynchronous structured research","deprecated":null,"version":null,"sidebarTitle":"Create go run","openapi":"/openapi.yaml post /v1/go/runs","href":"/api-reference/go/create-go-run"},{"title":"Go job status","deprecated":null,"version":null,"sidebarTitle":"Get go run","openapi":"/openapi.yaml get /v1/go/runs/{id}","href":"/api-reference/go/get-go-run"},{"title":"Cancel a Go job","deprecated":null,"version":null,"sidebarTitle":"Cancel go run","openapi":"/openapi.yaml post /v1/go/runs/{id}/cancel","href":"/api-reference/go/cancel-go-run"}]},{"group":"Services","pages":[{"title":"Discover services","deprecated":null,"version":null,"sidebarTitle":"List services","openapi":"/openapi.yaml get /services","href":"/api-reference/services/list-services"},{"title":"Describe a service (input schema, cost)","deprecated":null,"version":null,"sidebarTitle":"Get service","openapi":"/openapi.yaml get /services/{serviceName}","href":"/api-reference/services/get-service"},{"title":"Execute a service","deprecated":null,"version":null,"sidebarTitle":"Execute service","openapi":"/openapi.yaml post /services/{serviceName}","href":"/api-reference/services/execute-service"},{"title":"List your service jobs","deprecated":null,"version":null,"openapi":"/openapi.yaml get /v1/services/jobs","href":"/api-reference/services/list-your-service-jobs"},{"title":"Removed, send a list","deprecated":true,"version":null,"openapi":"/openapi.yaml post /v1/services/jobs","href":"/api-reference/services/removed-send-a-list"},{"title":"Service job status and result","deprecated":null,"version":null,"openapi":"/openapi.yaml get /v1/services/jobs/{id}","href":"/api-reference/services/service-job-status-and-result"},{"title":"Cancel a service job","deprecated":null,"version":null,"openapi":"/openapi.yaml post /v1/services/jobs/{id}/cancel","href":"/api-reference/services/cancel-a-service-job"},{"title":"Run a slow service (a list of 1 to 100 inputs)","deprecated":null,"version":null,"openapi":"/openapi.yaml post /v1/services/jobs/batch","href":"/api-reference/services/run-a-slow-service-a-list-of-1-to-100-inputs"},{"title":"Batch status and results","deprecated":null,"version":null,"openapi":"/openapi.yaml get /v1/services/jobs/batch/{id}","href":"/api-reference/services/batch-status-and-results"}]},{"group":"Credits","pages":[{"title":"Credit balance","deprecated":null,"version":null,"sidebarTitle":"Get credits","openapi":"/openapi.yaml get /credits","href":"/api-reference/credits/get-credits"}]}]}]},"basePath":"","title":"Request cancellation - Retriever API","buildId":"dpl_G9nrg4qeJSZtah1Ziwbc2n6WkLch","deploymentId":"dpl_G9nrg4qeJSZtah1Ziwbc2n6WkLch","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-B7XKH4J3.js","utils-lOYzL7z-.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-DF6jUUIM.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-Dpsj5f7C.js","snippetPresets-CYeiDe8v.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","ApiExamples-CUFz1YZ_.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-D8H_iLS4.js","shallow-DdluZBHX.js","getApiPlaygroundDisplay-B9922vev.js","CodeSnippet-CMoRNGYs.js","CodeSnippets-DwyrPHuw.js","Page-DSVu9Ucl.js","getPastedJson-G-zIvlHh.js","icon-B03fnEy0.js","MethodPill-CW7teklc.js","DuplicateIcon-CtO8eekd.js","createIcon-DZTKdM_A.js","DynamicMarkdown-D5M2At0B.js","SectionHeading-C_2NaA2U.js","axios-vUo_bRtp.js","Markdown-D7QRHV3m.js","clsx-D1Z-ELXV.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-lvhuD9Du.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-CKfC4ywL.js"]}