{
"error": {
"code": "invalid_request",
"message": "prompt: prompt must not be blank",
"details": [
{
"path": "prompt",
"message": "prompt must not be blank"
}
]
}
}
{
"error": {
"code": "not_authenticated",
"message": "A valid API key is required."
}
}
Registers the run and responds immediately with 202. Poll it with
GET /v1/runs/{id}. Without workspace_id or conversation_id,
Retriever creates a workspace and a conversation. To refine or extend
a result, send the conversation_id of the run that produced it: the
agent keeps its history and tables, and can add to the same table.
Open a new conversation for an unrelated request, or to run requests
at the same time.
Send an Idempotency-Key to safely retry the request without creating a
duplicate: same key + same body = same run; same key + different body =
409 idempotency_conflict.
An organization executes at most 5 runs at the same time by default. A
new run is never refused because of this limit. While all its slots
are taken, by runs
running or recovering or by older queued runs, it stays queued,
with a queue field saying why, then starts on its own, oldest first.
MCP runs share the same slots; Go jobs do not. A queued run already
holds its conversation (409 conversation_busy for a follow-up). Do not
create a queued run again: a second run is billed as a second run.
POST
/
v1
/
runs
curl --request POST \
--url https://api.retriever.run/v1/runs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "Find 30 French fintechs with 50 to 200 employees and their CEO."
}
'
{
"error": {
"code": "invalid_request",
"message": "prompt: prompt must not be blank",
"details": [
{
"path": "prompt",
"message": "prompt must not be blank"
}
]
}
}
{
"error": {
"code": "not_authenticated",
"message": "A valid API key is required."
}
}
Natural-language instruction. Must not be empty. The agent does not ask clarifying questions: put every decision here. A later run on the same conversation_id corrects a choice.
Existing workspace. Without conversation_id, the run opens a new conversation there; with it, it must be the conversation's workspace. Without both, a workspace is created.
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/create-run","slug":"/api-reference/runs/create-run","pageMetadata":{"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","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: [\"Registers the run and responds immediately with \", _jsx(_components.code, {\n children: \"202\"\n }), \". Poll it with\\n\", _jsx(_components.code, {\n children: \"GET /v1/runs/{id}\"\n }), \". Without \", _jsx(_components.code, {\n children: \"workspace_id\"\n }), \" or \", _jsx(_components.code, {\n children: \"conversation_id\"\n }), \",\\nRetriever creates a workspace and a conversation. To refine or extend\\na result, send the \", _jsx(_components.code, {\n children: \"conversation_id\"\n }), \" 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 }), \"\\n\", _jsxs(_components.p, {\n children: [\"Send an \", _jsx(_components.code, {\n children: \"Idempotency-Key\"\n }), \" to safely retry the request without creating a\\nduplicate: same key + same body = same run; same key + different body =\\n\", _jsx(_components.code, {\n children: \"409 idempotency_conflict\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"An 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\", _jsx(_components.code, {\n children: \"running\"\n }), \" or \", _jsx(_components.code, {\n children: \"recovering\"\n }), \" or by older queued runs, it stays \", _jsx(_components.code, {\n children: \"queued\"\n }), \",\\nwith a \", _jsx(_components.code, {\n children: \"queue\"\n }), \" 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 (\", _jsx(_components.code, {\n children: \"409 conversation_busy\"\n }), \" for a follow-up). Do not\\ncreate a queued run again: a second run is billed as a second run.\"]\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":"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","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"tags":["Runs"],"operationId":"createRun","x-mint":{"href":"/api-reference/runs/create-run"},"summary":"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","parameters":["812f8451-3ab0-4321-b342-e4962e7bdba1"],"requestBody":"81a4a034-d140-4dd3-8133-657ceb3d2671","responses":{"202":"c0e24449-b73e-4202-9363-683d4c54eb4a","400":"5484b7f4-d1a0-4f3e-82e7-fb974a3c4577","401":"503f2744-25b6-4cb0-8d15-830b9d6dac4c","404":"c30b6e28-b46d-4822-bf22-636fae5aeaec","409":"41db9763-9b48-4303-a7d4-b05900217a06","413":"478167a1-d531-4137-a21b-a922e9cd1e52","415":"ab4ae7f2-0a0b-4a80-8cb1-a6e7a443db72","429":"fc7b0933-61f9-4d94-844a-596efbe904c7","503":"c8f970f0-a0f0-4da3-b139-f800383e4214"},"method":"post","type":"path","servers":["f1f50859-a682-49e6-8d68-df5f1384c422","a55f1192-b1ce-44b1-9592-9a845f4f9936"],"security":["5359af61-e76c-4569-9ee1-184c3a970601"],"path":"/v1/runs","baseUrlOptions":["https://api.retriever.run","http://localhost:4320"],"title":"Start a run","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"812f8451-3ab0-4321-b342-e4962e7bdba1":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"isRequired":false,"description":"Unique client-side request id (e.g. UUID). Must not be empty.","uniqueKey":"","typeLabel":"string"},"description":"Unique client-side request id (e.g. UUID). Must not be empty."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["prompt"],"properties":{"prompt":{"type":"string","minLength":1,"description":"Natural-language instruction. Must not be empty. The agent does not ask clarifying questions: put every decision here. A later run on the same conversation_id corrects a choice.","isRequired":true,"uniqueKey":"prompt","typeLabel":"string"},"workspace_id":{"type":"string","description":"Existing workspace. Without `conversation_id`, the run opens a new conversation there; with it, it must be the conversation's workspace. Without both, a workspace is created.","uniqueKey":"workspace_id","typeLabel":"string"},"conversation_id":{"type":"string","description":"Continues this conversation: the agent keeps its history and tables. Use it to refine or extend an earlier result.","uniqueKey":"conversation_id","typeLabel":"string"},"output":{"oneOf":[{"type":"object","description":"Optional output contract. Without it, the run returns `message`,\n`artifacts`, and `output: null`.\n","required":["type","schema"],"properties":{"type":{"const":"json","isRequired":true,"uniqueKey":"output.oneOf.0.type","typeLabel":"any"},"schema":{"oneOf":[{"description":"Standalone JSON Schema draft 7. Output is validated without coercion.","type":"object","isRequired":true,"uniqueKey":"output.oneOf.0.schema.oneOf.0","typeLabel":"object"},{"description":"Standalone JSON Schema draft 7. Output is validated without coercion.","type":"boolean","isRequired":true,"uniqueKey":"output.oneOf.0.schema.oneOf.1","typeLabel":"boolean"}],"isRequired":true,"uniqueKey":"output.oneOf.0.schema","typeLabel":"object | boolean"}},"additionalProperties":false,"uniqueKey":"output.oneOf.0","typeLabel":"object"},{"type":"object","description":"Optional output contract. Without it, the run returns `message`,\n`artifacts`, and `output: null`.\n","required":["type"],"properties":{"type":{"const":"tables","isRequired":true,"uniqueKey":"output.oneOf.1.type","typeLabel":"any"},"tables":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["key"],"properties":{"key":{"type":"string","minLength":1,"description":"Unique key in the contract.","isRequired":true,"uniqueKey":"output.oneOf.1.tables.items.[INDEX].key","typeLabel":"string"},"row_schema":{"oneOf":[{"type":"object","description":"JSON Schema enforced on each row's `values`.","uniqueKey":"output.oneOf.1.tables.items.[INDEX].row_schema.oneOf.0","typeLabel":"object"},{"type":"boolean","description":"JSON Schema enforced on each row's `values`.","uniqueKey":"output.oneOf.1.tables.items.[INDEX].row_schema.oneOf.1","typeLabel":"boolean"}],"uniqueKey":"output.oneOf.1.tables.items.[INDEX].row_schema","typeLabel":"object | boolean"}},"uniqueKey":"output.oneOf.1.tables.items.[INDEX]","typeLabel":"object"},"uniqueKey":"output.oneOf.1.tables","typeLabel":"object[]"}},"additionalProperties":false,"uniqueKey":"output.oneOf.1","typeLabel":"object"}],"uniqueKey":"output","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"simple":{"title":"simple","value":{"prompt":"Find 30 French fintechs with 50 to 200 employees and their CEO."}},"frozenTable":{"title":"frozenTable","value":{"prompt":"Find the CEO and their LinkedIn for each company in table tbl_001.","workspace_id":"ws_001","output":{"type":"tables","tables":[{"key":"contacts"}]}}}},"exampleType":"examples"}},"exampleType":"examples"},"responses":{"c0e24449-b73e-4202-9363-683d4c54eb4a":{"description":"Run accepted.","headers":{"Location":{"schema":{"type":"string"},"description":"Run path, e.g. /v1/runs/run_001."},"Retry-After":{"schema":{"type":"integer"},"description":"Suggested delay before the first poll (5 s)."},"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","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"},"5484b7f4-d1a0-4f3e-82e7-fb974a3c4577":{"description":"`invalid_request`: unreadable JSON, unknown field or query parameter, wrong type, `limit` out of range, empty `Idempotency-Key`, invalid `output` contract. `message` names each invalid field; `details` lists them as `{ path, message }`. On `POST /v1/runs`, `workspace_mismatch`: the conversation does not belong to the provided workspace.","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":"invalid_request","message":"prompt: prompt must not be blank","details":[{"path":"prompt","message":"prompt must not be blank"}]}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"invalid_request","message":"prompt: prompt must not be blank","details":[{"path":"prompt","message":"prompt must not be blank"}]}}}},"exampleType":"examples"}},"exampleType":"examples"},"503f2744-25b6-4cb0-8d15-830b9d6dac4c":{"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"},"c30b6e28-b46d-4822-bf22-636fae5aeaec":{"description":"`workspace_not_found` or `conversation_not_found`.","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"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"\u003cstring>","message":"\u003cstring>","details":"\u003cunknown>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"41db9763-9b48-4303-a7d4-b05900217a06":{"description":"`idempotency_conflict` (same key, different body) or `conversation_busy` (a run is already active in this conversation).","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":"conversation_busy","message":"This conversation already has an active run."}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"conversation_busy","message":"This conversation already has an active run."}}}},"exampleType":"examples"}},"exampleType":"examples"},"478167a1-d531-4137-a21b-a922e9cd1e52":{"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"},"ab4ae7f2-0a0b-4a80-8cb1-a6e7a443db72":{"description":"`invalid_request`: add `Content-Type: application/json`.","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":"invalid_request","message":"Content-Type must be application/json."}},"examples":{"Example":{"title":"Example","value":{"error":{"code":"invalid_request","message":"Content-Type must be application/json."}}}},"exampleType":"examples"}},"exampleType":"examples"},"fc7b0933-61f9-4d94-844a-596efbe904c7":{"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"},"c8f970f0-a0f0-4da3-b139-f800383e4214":{"description":"`runs_unavailable`: run storage unavailable. Try again later.","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"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"\u003cstring>","message":"\u003cstring>","details":"\u003cunknown>"}}}},"exampleType":"generated"}},"exampleType":"generated"}},"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":"Start a run - Retriever API","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-16T06:30:58.229Z","originalFileLocation":"api-reference/runs/create-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=\"Registers the run and responds immediately with 202. Poll it with GET /v1/runs/{id}. Without workspace_id or conversation_id, Retriever creates a workspace and a conversation. To refine or extend a result, send the conversation_id of the run that produced it: the agent keeps its history and tables, and can add to the same table. Open a new conversation for an unrelated request, or to run requests at the same time. Send an Idempotency-Key to safely retry the request without creating a duplicate: same key + same body = same run; same key + different body = 409 idempotency_conflict. An organization executes at most 5 runs at the same time by default. A new run is never refused because of this limit. While all its slots are taken, by runs running or recovering or by older queued runs, it stays queued, with a queue field saying why, then starts on its own, oldest first. MCP runs share the same slots; Go jobs do not. A queued run already holds its conversation (409 conversation_busy for a follow-up). Do not create a queued run again: a second run is billed as a second run.\">\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=\"Start a run - Retriever API\">\u003cmeta data-mint-head property=\"og:description\" content=\"Registers the run and responds immediately with 202. Poll it with GET /v1/runs/{id}. Without workspace_id or conversation_id, Retriever creates a workspace and a conversation. To refine or extend a result, send the conversation_id of the run that produced it: the agent keeps its history and tables, and can add to the same table. Open a new conversation for an unrelated request, or to run requests at the same time. Send an Idempotency-Key to safely retry the request without creating a duplicate: same key + same body = same run; same key + different body = 409 idempotency_conflict. An organization executes at most 5 runs at the same time by default. A new run is never refused because of this limit. While all its slots are taken, by runs running or recovering or by older queued runs, it stays queued, with a queue field saying why, then starts on its own, oldest first. MCP runs share the same slots; Go jobs do not. A queued run already holds its conversation (409 conversation_busy for a follow-up). Do not create a queued run again: a second run is billed as a second run.\">\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/create-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=Start+a+run\u0026amp;description=Registers+the+run+and+responds+immediately+with+%60202%60.+Poll+it+with%0A%60GET+%2Fv1%2Fruns%2F%7Bid%7D%60.+Without+%60workspace_id%60+or+%60conversation_id%60%2C%0ARetriever+creates+a+worksp\u0026amp;theme=4c917abfdccf5db373a73b47\u0026amp;signature=e6b42cc758bd45b8f7cea0249942eb606ec32cb22bb7d4ffa05efdd87578170c\">\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=\"Start a run - Retriever API\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Registers the run and responds immediately with 202. Poll it with GET /v1/runs/{id}. Without workspace_id or conversation_id, Retriever creates a workspace and a conversation. To refine or extend a result, send the conversation_id of the run that produced it: the agent keeps its history and tables, and can add to the same table. Open a new conversation for an unrelated request, or to run requests at the same time. Send an Idempotency-Key to safely retry the request without creating a duplicate: same key + same body = same run; same key + different body = 409 idempotency_conflict. An organization executes at most 5 runs at the same time by default. A new run is never refused because of this limit. While all its slots are taken, by runs running or recovering or by older queued runs, it stays queued, with a queue field saying why, then starts on its own, oldest first. MCP runs share the same slots; Go jobs do not. A queued run already holds its conversation (409 conversation_busy for a follow-up). Do not create a queued run again: a second run is billed as a second run.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://retriever-3987567e.mintlify.app/_mintlify/api/og/v2?division=Runs\u0026amp;title=Start+a+run\u0026amp;description=Registers+the+run+and+responds+immediately+with+%60202%60.+Poll+it+with%0A%60GET+%2Fv1%2Fruns%2F%7Bid%7D%60.+Without+%60workspace_id%60+or+%60conversation_id%60%2C%0ARetriever+creates+a+worksp\u0026amp;theme=4c917abfdccf5db373a73b47\u0026amp;signature=e6b42cc758bd45b8f7cea0249942eb606ec32cb22bb7d4ffa05efdd87578170c\">\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/create-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/create-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/create-run#webpage\",\"url\":\"https://docs.retriever.run/api-reference/runs/create-run\",\"name\":\"Start a run\",\"description\":\"Registers the run and responds immediately with 202. Poll it with GET /v1/runs/{id}. Without workspace_id or conversation_id, Retriever creates a workspace and a conversation. To refine or extend a result, send the conversation_id of the run that produced it: the agent keeps its history and tables, and can add to the same table. Open a new conversation for an unrelated request, or to run requests at the same time. Send an Idempotency-Key to safely retry the request without creating a duplicate: same key + same body = same run; same key + different body = 409 idempotency_conflict. An organization executes at most 5 runs at the same time by default. A new run is never refused because of this limit. While all its slots are taken, by runs running or recovering or by older queued runs, it stays queued, with a queue field saying why, then starts on its own, oldest first. MCP runs share the same slots; Go jobs do not. A queued run already holds its conversation (409 conversation_busy for a follow-up). Do not create a queued run again: a second run is billed as a second run.\",\"dateModified\":\"2026-10-16T06:30:58.229Z\",\"isPartOf\":{\"@id\":\"https://docs.retriever.run#website\"},\"breadcrumb\":{\"@id\":\"https://docs.retriever.run/api-reference/runs/create-run#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.retriever.run/api-reference/runs/create-run#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Runs\",\"item\":\"https://docs.retriever.run/api-reference/runs/list-runs\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Start a run\",\"item\":\"https://docs.retriever.run/api-reference/runs/create-run\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.retriever.run/api-reference/runs/create-run#apireference\",\"headline\":\"Start a run\",\"name\":\"Start a run\",\"description\":\"Registers the run and responds immediately with 202. Poll it with GET /v1/runs/{id}. Without workspace_id or conversation_id, Retriever creates a workspace and a conversation. To refine or extend a result, send the conversation_id of the run that produced it: the agent keeps its history and tables, and can add to the same table. Open a new conversation for an unrelated request, or to run requests at the same time. Send an Idempotency-Key to safely retry the request without creating a duplicate: same key + same body = same run; same key + different body = 409 idempotency_conflict. An organization executes at most 5 runs at the same time by default. A new run is never refused because of this limit. While all its slots are taken, by runs running or recovering or by older queued runs, it stays queued, with a queue field saying why, then starts on its own, oldest first. MCP runs share the same slots; Go jobs do not. A queued run already holds its conversation (409 conversation_busy for a follow-up). Do not create a queued run again: a second run is billed as a second run.\",\"url\":\"https://docs.retriever.run/api-reference/runs/create-run\",\"mainEntityOfPage\":{\"@id\":\"https://docs.retriever.run/api-reference/runs/create-run#webpage\"},\"dateModified\":\"2026-10-16T06:30:58.229Z\",\"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","description":null,"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","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":"Start a run - 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"]}