Poll until a terminal status (completed, failed, cancelled).
Honor Retry-After (15 s for an active run). Send If-None-Match with
the ETag from a prior read to get 304 when nothing changed.
Only this read returns credits.charged, the credits the run was
charged so far. The list, create and cancel responses leave it out.
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/get-run","slug":"/api-reference/runs/get-run","pageMetadata":{"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","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, 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(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"Poll until a terminal status (\", _jsx(_components.code, {\n children: \"completed\"\n }), \", \", _jsx(_components.code, {\n children: \"failed\"\n }), \", \", _jsx(_components.code, {\n children: \"cancelled\"\n }), \").\\nHonor \", _jsx(_components.code, {\n children: \"Retry-After\"\n }), \" (15 s for an active run). Send \", _jsx(_components.code, {\n children: \"If-None-Match\"\n }), \" with\\nthe \", _jsx(_components.code, {\n children: \"ETag\"\n }), \" from a prior read to get \", _jsx(_components.code, {\n children: \"304\"\n }), \" when nothing changed.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Only this read returns \", _jsx(_components.code, {\n children: \"credits.charged\"\n }), \", the credits the run was\\ncharged so far. The list, create and cancel responses leave it out.\"]\n })]\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":"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","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"tags":["Runs"],"operationId":"getRun","x-mint":{"href":"/api-reference/runs/get-run"},"summary":"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","parameters":["e7ce6d0d-f069-4507-8552-9aca6f7a64db","0a8eec5c-46a0-4254-b844-0549e305948c"],"responses":{"200":"ce47f3a4-eea9-4aef-bc34-9ec9a0ac953f","304":"6c3c13d6-11cc-4fd9-832a-7aad74506636","401":"cab77712-92e4-47a5-8837-d51e9ffa517b","404":"e8a3d166-67fd-4eb3-a563-2414f5dc11c3","429":"a53949c9-ebfe-4493-9386-ec0a08cc0b6b"},"method":"get","type":"path","servers":["f1f50859-a682-49e6-8d68-df5f1384c422","a55f1192-b1ce-44b1-9592-9a845f4f9936"],"security":["5359af61-e76c-4569-9ee1-184c3a970601"],"path":"/v1/runs/{id}","baseUrlOptions":["https://api.retriever.run","http://localhost:4320"],"title":"Get run status","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"e7ce6d0d-f069-4507-8552-9aca6f7a64db":{"name":"id","in":"path","required":true,"schema":{"type":"string","isRequired":true,"uniqueKey":"","typeLabel":"string"},"example":"run_001"},"0a8eec5c-46a0-4254-b844-0549e305948c":{"name":"If-None-Match","in":"header","schema":{"type":"string","description":"ETag from a previous read.","uniqueKey":"","typeLabel":"string"},"description":"ETag from a previous read."}},"responses":{"ce47f3a4-eea9-4aef-bc34-9ec9a0ac953f":{"description":"Current state.","headers":{"ETag":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"integer"},"description":"Present only while the run is active."}},"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"},"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,"credits":{"charged":42.5},"cancellation_requested":false,"links":{"self":"/v1/runs/run_001","app":"https://app.retriever.run/app/workspaces/ws_001/conversations/conv_001"}},"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,"credits":{"charged":42.5},"cancellation_requested":false,"links":{"self":"/v1/runs/run_001","app":"https://app.retriever.run/app/workspaces/ws_001/conversations/conv_001"}}}},"exampleType":"examples"}},"exampleType":"examples"},"6c3c13d6-11cc-4fd9-832a-7aad74506636":{"description":"Unchanged since the provided ETag.","content":{"_mintlify/placeholder":{"schema":{"type":"object","description":""}}}},"cab77712-92e4-47a5-8837-d51e9ffa517b":{"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"},"e8a3d166-67fd-4eb3-a563-2414f5dc11c3":{"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"},"a53949c9-ebfe-4493-9386-ec0a08cc0b6b":{"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":"Get run status - Retriever API","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-16T06:30:58.239Z","originalFileLocation":"api-reference/runs/get-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=\"Poll until a terminal status (completed, failed, cancelled). Honor Retry-After (15 s for an active run). Send If-None-Match with the ETag from a prior read to get 304 when nothing changed. Only this read returns credits.charged, the credits the run was charged so far. The list, create and cancel responses leave it out.\">\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=\"Get run status - Retriever API\">\u003cmeta data-mint-head property=\"og:description\" content=\"Poll until a terminal status (completed, failed, cancelled). Honor Retry-After (15 s for an active run). Send If-None-Match with the ETag from a prior read to get 304 when nothing changed. Only this read returns credits.charged, the credits the run was charged so far. The list, create and cancel responses leave it out.\">\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/get-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=Get+run+status\u0026amp;description=Poll+until+a+terminal+status+%28%60completed%60%2C+%60failed%60%2C+%60cancelled%60%29.%0AHonor+%60Retry-After%60+%2815+s+for+an+active+run%29.+Send+%60If-None-Match%60+with%0Athe+%60ETag%60+from+a+pri\u0026amp;theme=4c917abfdccf5db373a73b47\u0026amp;signature=00c1357848e606853174e700c164b50add65a76bdd55e5e8402a37e98cc9298e\">\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=\"Get run status - Retriever API\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Poll until a terminal status (completed, failed, cancelled). Honor Retry-After (15 s for an active run). Send If-None-Match with the ETag from a prior read to get 304 when nothing changed. Only this read returns credits.charged, the credits the run was charged so far. The list, create and cancel responses leave it out.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://retriever-3987567e.mintlify.app/_mintlify/api/og/v2?division=Runs\u0026amp;title=Get+run+status\u0026amp;description=Poll+until+a+terminal+status+%28%60completed%60%2C+%60failed%60%2C+%60cancelled%60%29.%0AHonor+%60Retry-After%60+%2815+s+for+an+active+run%29.+Send+%60If-None-Match%60+with%0Athe+%60ETag%60+from+a+pri\u0026amp;theme=4c917abfdccf5db373a73b47\u0026amp;signature=00c1357848e606853174e700c164b50add65a76bdd55e5e8402a37e98cc9298e\">\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/get-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/get-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/get-run#webpage\",\"url\":\"https://docs.retriever.run/api-reference/runs/get-run\",\"name\":\"Get run status\",\"description\":\"Poll until a terminal status (completed, failed, cancelled). Honor Retry-After (15 s for an active run). Send If-None-Match with the ETag from a prior read to get 304 when nothing changed. Only this read returns credits.charged, the credits the run was charged so far. The list, create and cancel responses leave it out.\",\"dateModified\":\"2026-10-16T06:30:58.239Z\",\"isPartOf\":{\"@id\":\"https://docs.retriever.run#website\"},\"breadcrumb\":{\"@id\":\"https://docs.retriever.run/api-reference/runs/get-run#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.retriever.run/api-reference/runs/get-run#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Runs\",\"item\":\"https://docs.retriever.run/api-reference/runs/list-runs\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Get run status\",\"item\":\"https://docs.retriever.run/api-reference/runs/get-run\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.retriever.run/api-reference/runs/get-run#apireference\",\"headline\":\"Get run status\",\"name\":\"Get run status\",\"description\":\"Poll until a terminal status (completed, failed, cancelled). Honor Retry-After (15 s for an active run). Send If-None-Match with the ETag from a prior read to get 304 when nothing changed. Only this read returns credits.charged, the credits the run was charged so far. The list, create and cancel responses leave it out.\",\"url\":\"https://docs.retriever.run/api-reference/runs/get-run\",\"mainEntityOfPage\":{\"@id\":\"https://docs.retriever.run/api-reference/runs/get-run#webpage\"},\"dateModified\":\"2026-10-16T06:30:58.239Z\",\"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","description":"Registers the run and responds immediately with `202`. Poll it with\n`GET /v1/runs/{id}`. Without `workspace_id` or `conversation_id`,\nRetriever creates a workspace and a conversation. To refine or extend\na result, send the `conversation_id` of the run that produced it: the\nagent keeps its history and tables, and can add to the same table.\nOpen a new conversation for an unrelated request, or to run requests\nat the same time.\n\nSend an `Idempotency-Key` to safely retry the request without creating a\nduplicate: same key + same body = same run; same key + different body =\n`409 idempotency_conflict`.\n\nAn organization executes at most 5 runs at the same time by default. A\nnew run is never refused because of this limit. While all its slots\nare taken, by runs\n`running` or `recovering` or by older queued runs, it stays `queued`,\nwith a `queue` field saying why, then starts on its own, oldest first.\nMCP runs share the same slots; Go jobs do not. A queued run already\nholds its conversation (`409 conversation_busy` for a follow-up). Do not\ncreate a queued run again: a second run is billed as a second run.\n","deprecated":null,"version":null,"sidebarTitle":"Create run","openapi":"/openapi.yaml post /v1/runs","href":"/api-reference/runs/create-run"},{"title":"Get run status","deprecated":null,"version":null,"sidebarTitle":"Get run","openapi":"/openapi.yaml get /v1/runs/{id}","href":"/api-reference/runs/get-run"},{"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"},{"title":"Get published output","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":"Get run status - 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"]}