Returns the run as it is now. With waitMs it waits for the state to leave sinceState and returns as soon as it does, or at the deadline with whatever the state is then. It never hangs: the transport is stateless and there is no push channel.
EITHER ID WORKS HERE. Send the runIdPOST /v1/runs returned, or the run’s agentRunId: the id every receipt the run produced carries and the one a permalink is built on. An id starting run_ is read as an agentRunId, anything else as a runId. Both answer with the same run through the same checks, waitMs included. The writes below take a runId only.
This returns the run only. Its action trail is a separate, paged resource, GET /v1/receipts?agentRunId=..., and it is not folded in here: it is a paged collection with its own cursor and its own retention.
This route applies the calling key’s device narrowing: a run on a device your key cannot address is 404, the same 404 an unknown id gets.
GET
/
v1
/
runs
/
{runId}
Error
A valid request URL is required to generate request examples
The control surface credential. Send Authorization: Bearer <token>.
Two kinds of token are accepted and they are told apart by shape, not by a separate header. A token beginning pbk_ or puk_ is an org scoped API key, whose public half and secret half are generated together and of which only a hash of the secret is ever stored; anything else is treated as an OAuth 2.1 access token and verified against the authorization server's keys.
Both resolve to the same context: an org, a principal and a set of scopes. Nothing downstream branches on which channel you used, with one deliberate exception, key management, which requires a signed-in person so that a key can never mint another key.
Scopes are enforced when MCP tools are REGISTERED rather than when they are called, so a tool your credential cannot use is absent from tools/list rather than refused mid gesture.
Path Parameters
runId
string
required
The runId returned when the run was started, or the run's agentRunId (it starts run_).
Query Parameters
waitMs
integer
How long to wait for a state change, in whole milliseconds, 0 to 25000 (25 seconds). A longer wait is refused, not shortened: loop on the call instead of holding one open.
Required range: 0 <= x <= 25000
sinceState
enum<string>
Return as soon as the state is no longer this one. Without it, the call returns immediately. Must be one of the run states: an unknown value is refused rather than treated as a state the run is never in.
A run state.
Available options:
queued,
running,
needs_user_control,
paused,
succeeded,
failed,
canceled
Response
The run.
The public projection of a run, and who started it. The run token is deliberately absent: it is returned once, when the run is started, and never again.
runId
string
required
agentRunId
string
required
deviceId
string
required
goal
string
required
What the run was asked to accomplish, in the words it was started with.
executor
enum<string>
required
Who drives this run: phoneuse (we do) or self_hosted (your worker does).
Available options:
phoneuse,
self_hosted
state
enum<string>
required
Where the run is now. succeeded, failed and canceled are terminal. paused means a person put the agent on hold: the worker's channels are shut until Resume. It is not needs_user_control, which can mean the agent is asking for help or an interrupted hosted run is waiting for explicit continuation. A non-null recovery distinguishes the latter.
Available options:
queued,
running,
needs_user_control,
paused,
succeeded,
failed,
canceled
stepSeq
integer
required
Metered steps issued so far. One step is one frame served.
maxSteps
integer
required
The run's step ceiling.
deadlineAt
string<date-time> | null
required
Absolute wall clock deadline, or null when the stored deadline is not a renderable instant. FROZEN while the run is paused: the time the agent spends on hold is not charged to the run, and resuming slides this forward by however long the hold lasted. It is null during recovery waiting; recovery.remainingMs reports the saved time budget.
createdAt
string<date-time>
required
updatedAt
string<date-time>
required
workerFirstContactAt
string<date-time> | null
required
When a self-hosted worker first reached this run, or null when none ever did. On a self_hosted run you supply the worker, and one that stays queued with null here is waiting for it. A phoneuse run is driven in process and never sets this.
initiator
object
required
WHO. The same shape answers three questions: who took an action (Receipt.actor), who is holding a device (Lease.holder), and who started a run (RunView.initiator). One shape on purpose, so the three can never disagree about what a given credential is called.
Show child attributes
scheduleId
string | null
required
The schedule that started this run, or null when a person or a key did. Present and null rather than absent, so you can tell those apart from an older server that does not say. Schedules were retired, so a run started now is always null here; only an older run can carry an id.
pausedAt
string<date-time> | null
required
When a person put the run on hold, or null when it is not on hold. Present and null rather than absent, so a consumer can tell "not on hold" from an older server that does not report it.
manualControlUntil
string<date-time> | null
required
When the hold ends, or null when the run is not paused. This is the clock that runs while the run is on hold, not deadlineAt. Past it, a run nobody resumed is canceled with an explanation in detail; no new failure reason is used. The name is kept from when a hold was a person's manual control window; a person needs no window to act on the device now.
lastFrame
object | null
required
The last frame this run was served, or null when it has been served none. On a finished run this is the frame the model's report was written from, because finish_run ends the turn and nothing is captured after it, so a reader can put what the model said next to the screen it read that off. viewport is the frame's own pixel geometry, which is the coordinate basis it was captured in and not necessarily the device's current size.
Show child attributes
recovery
object | null
An interrupted hosted run waiting for explicit continuation, or null. Older servers may omit this field. Progress and remaining budget are preserved; no action is replayed automatically.
Show child attributes
progress
object
Optional original confirmed-plan progress from a fresh committed read. Legacy runs have no synthesized proof; historical facts grant no new effects.
Show child attributes
reason
enum<string>
Why the run ended, when it did not simply succeed.
Available options:
worker_reported_failure,
budget_exhausted,
deadline_exceeded,
canceled_by_caller,
lease_lost,
interrupted_by_restart
detail
string
Free text about how the run ended. A worker's own report, or, when the run hit its deadline, the control plane's explanation of which kind of timeout it was.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"PhoneUse","description":"The mobile execution layer for AI agents.","colors":{"primary":"#0c6b4f","light":"#12a06a","dark":"#0a5a43"},"logo":{"light":"https://mintcdn.com/phonebase/asSC9ooLxq3ce7AH/images/logo-light.svg?fit=max\u0026auto=format\u0026n=asSC9ooLxq3ce7AH\u0026q=85\u0026s=797a832db8f0e271d5dbd6beba29a27b","dark":"https://mintcdn.com/phonebase/asSC9ooLxq3ce7AH/images/logo-dark.svg?fit=max\u0026auto=format\u0026n=asSC9ooLxq3ce7AH\u0026q=85\u0026s=82325f8969ce89102cc6e3af558a4436","href":"https://phoneuse.com"},"favicon":"https://mintcdn.com/phonebase/asSC9ooLxq3ce7AH/images/favicon.svg?fit=max\u0026auto=format\u0026n=asSC9ooLxq3ce7AH\u0026q=85\u0026s=5aebe1e05fdad8394b3f4d54e6e75f22","appearance":{"default":"light"},"navbar":{"primary":{"type":"button","label":"Main site","href":"https://phoneuse.com"}},"footer":{"socials":{"website":"https://phoneuse.com"}},"contextual":{"options":["copy","view","claude","chatgpt","cursor","vscode","mcp"],"display":"header"},"styling":{"latex":true},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"phonebase","hasAudioNarration":false,"actualSubdomain":"phonebase","customDomains":["docs.phoneuse.com"],"gitSource":{"type":"github","owner":"phoneuse-official","repo":"phoneuse-api","deployBranch":"docs-release","contentDirectory":"docs/site","isPrivate":true,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6afd0a6c8745fb0d64fce35c","clientVersion":"0.0.4248","searchFilterCounts":[{"language":"default","tag":"API","count":158},{"language":"default","tag":"Endpoints","count":155},{"language":"default","tag":"Docs","count":34},{"language":"default","tag":"Managed Proxy","count":22},{"language":"default","tag":"Minute billing","count":22},{"language":"default","tag":"Devices","count":19},{"language":"default","tag":"Apps","count":18},{"language":"default","tag":"Provisioning","count":14},{"language":"default","tag":"API keys","count":12},{"language":"default","tag":"Copilot","count":10}]},"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":"custom-rbac-roles","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":"rbac-expansion","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":"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":"site-roles","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":"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":"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},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"treatment","enabled":true,"payload":{"type":"string","value":"treatment"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[]}
{"page":{"pagePath":"api/endpoints/runs/read-a-run-optionally-waiting-for-it-to-move","slug":"/api/endpoints/runs/read-a-run-optionally-waiting-for-it-to-move","pageMetadata":{"title":"Read a run, optionally waiting for it to move","description":"Returns the run as it is now. With `waitMs` it waits for the state to leave `sinceState` and returns as soon as it does, or at the deadline with whatever the state is then. It never hangs: the transport is stateless and there is no push channel.\n\nEITHER ID WORKS HERE. Send the `runId` `POST /v1/runs` returned, or the run's `agentRunId`: the id every receipt the run produced carries and the one a permalink is built on. An id starting `run_` is read as an agentRunId, anything else as a runId. Both answer with the same run through the same checks, `waitMs` included. The writes below take a runId only.\n\nThis returns the run only. Its action trail is a separate, paged resource, `GET /v1/receipts?agentRunId=...`, and it is not folded in here: it is a paged collection with its own cursor and its own retention.\n\nThis route applies the calling key's device narrowing: a run on a device your key cannot address is 404, the same 404 an unknown id gets.","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/runs/{runId}","href":"/api/endpoints/runs/read-a-run-optionally-waiting-for-it-to-move","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: [\"Returns the run as it is now. With \", _jsx(_components.code, {\n children: \"waitMs\"\n }), \" it waits for the state to leave \", _jsx(_components.code, {\n children: \"sinceState\"\n }), \" and returns as soon as it does, or at the deadline with whatever the state is then. It never hangs: the transport is stateless and there is no push channel.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"EITHER ID WORKS HERE. Send the \", _jsx(_components.code, {\n children: \"runId\"\n }), \" \", _jsx(_components.code, {\n children: \"POST /v1/runs\"\n }), \" returned, or the run’s \", _jsx(_components.code, {\n children: \"agentRunId\"\n }), \": the id every receipt the run produced carries and the one a permalink is built on. An id starting \", _jsx(_components.code, {\n children: \"run_\"\n }), \" is read as an agentRunId, anything else as a runId. Both answer with the same run through the same checks, \", _jsx(_components.code, {\n children: \"waitMs\"\n }), \" included. The writes below take a runId only.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"This returns the run only. Its action trail is a separate, paged resource, \", _jsx(_components.code, {\n children: \"GET /v1/receipts?agentRunId=...\"\n }), \", and it is not folded in here: it is a paged collection with its own cursor and its own retention.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"This route applies the calling key’s device narrowing: a run on a device your key cannot address is 404, the same 404 an unknown id gets.\"\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":"Read a run, optionally waiting for it to move","description":"Returns the run as it is now. With `waitMs` it waits for the state to leave `sinceState` and returns as soon as it does, or at the deadline with whatever the state is then. It never hangs: the transport is stateless and there is no push channel.\n\nEITHER ID WORKS HERE. Send the `runId` `POST /v1/runs` returned, or the run's `agentRunId`: the id every receipt the run produced carries and the one a permalink is built on. An id starting `run_` is read as an agentRunId, anything else as a runId. Both answer with the same run through the same checks, `waitMs` included. The writes below take a runId only.\n\nThis returns the run only. Its action trail is a separate, paged resource, `GET /v1/receipts?agentRunId=...`, and it is not folded in here: it is a paged collection with its own cursor and its own retention.\n\nThis route applies the calling key's device narrowing: a run on a device your key cannot address is 404, the same 404 an unknown id gets.","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/runs/{runId}","href":"/api/endpoints/runs/read-a-run-optionally-waiting-for-it-to-move","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"operationId":"getV1RunsByRunId","tags":["Runs"],"summary":"Read a run, optionally waiting for it to move","description":"Returns the run as it is now. With `waitMs` it waits for the state to leave `sinceState` and returns as soon as it does, or at the deadline with whatever the state is then. It never hangs: the transport is stateless and there is no push channel.\n\nEITHER ID WORKS HERE. Send the `runId` `POST /v1/runs` returned, or the run's `agentRunId`: the id every receipt the run produced carries and the one a permalink is built on. An id starting `run_` is read as an agentRunId, anything else as a runId. Both answer with the same run through the same checks, `waitMs` included. The writes below take a runId only.\n\nThis returns the run only. Its action trail is a separate, paged resource, `GET /v1/receipts?agentRunId=...`, and it is not folded in here: it is a paged collection with its own cursor and its own retention.\n\nThis route applies the calling key's device narrowing: a run on a device your key cannot address is 404, the same 404 an unknown id gets.","x-phoneuse-modes":["local","hosted"],"x-phoneuse-credential":"bearer","parameters":["1c4f4bb3-e044-416d-9415-2ee463440332","5b957443-bd5a-4355-9b16-1893c3dda964","51f86548-cab0-4119-9c50-e16730ff8906"],"security":["edc6a97f-6382-4ebd-b9df-7f5c5e17fd48"],"responses":{"200":"c491f246-cf30-477d-bc57-b60cd372bc1b","400":"fcd55eee-c5aa-4ff0-9cb0-70bad1671786","401":"e1a49f53-98bb-4737-9996-fe1032dcfcd6","403":"da55db36-43a1-4875-8bcf-3a01cd56b90c","404":"73e23f92-4c17-435b-8c55-abe06b56b93b","429":"e363f228-6c58-43af-a2cb-c80395c48a80","503":"1be104d5-c436-4e4f-ae36-651294c1d718"},"method":"get","type":"path","servers":["0b8b9ab5-c46d-4bb8-88b0-6eeb0d5654ea"],"path":"/v1/runs/{runId}","baseUrlOptions":["{origin}"],"title":"Read a run, optionally waiting for it to move","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"1c4f4bb3-e044-416d-9415-2ee463440332":{"name":"runId","in":"path","required":true,"description":"The runId returned when the run was started, or the run's agentRunId (it starts `run_`).","schema":{"type":"string","isRequired":true,"description":"The runId returned when the run was started, or the run's agentRunId (it starts `run_`).","uniqueKey":"","typeLabel":"string"}},"5b957443-bd5a-4355-9b16-1893c3dda964":{"name":"waitMs","in":"query","required":false,"description":"How long to wait for a state change, in whole milliseconds, 0 to 25000 (25 seconds). A longer wait is refused, not shortened: loop on the call instead of holding one open.","schema":{"type":"integer","minimum":0,"maximum":25000,"isRequired":false,"description":"How long to wait for a state change, in whole milliseconds, 0 to 25000 (25 seconds). A longer wait is refused, not shortened: loop on the call instead of holding one open.","uniqueKey":"","typeLabel":"integer"}},"51f86548-cab0-4119-9c50-e16730ff8906":{"name":"sinceState","in":"query","required":false,"description":"Return as soon as the state is no longer this one. Without it, the call returns immediately. Must be one of the run states: an unknown value is refused rather than treated as a state the run is never in.","schema":{"type":"string","enum":["queued","running","needs_user_control","paused","succeeded","failed","canceled"],"description":"Return as soon as the state is no longer this one. Without it, the call returns immediately. Must be one of the run states: an unknown value is refused rather than treated as a state the run is never in.\nA run state.","isRequired":false,"uniqueKey":"","typeLabel":"enum\u003cstring>"}}},"responses":{"c491f246-cf30-477d-bc57-b60cd372bc1b":{"description":"The run.","content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string","isRequired":true,"uniqueKey":"runId","typeLabel":"string"},"agentRunId":{"type":"string","isRequired":true,"uniqueKey":"agentRunId","typeLabel":"string"},"deviceId":{"type":"string","isRequired":true,"uniqueKey":"deviceId","typeLabel":"string"},"goal":{"type":"string","description":"What the run was asked to accomplish, in the words it was started with.","isRequired":true,"uniqueKey":"goal","typeLabel":"string"},"executor":{"type":"string","enum":["phoneuse","self_hosted"],"description":"Who drives this run: `phoneuse` (we do) or `self_hosted` (your worker does).","isRequired":true,"uniqueKey":"executor","typeLabel":"enum\u003cstring>"},"state":{"type":"string","enum":["queued","running","needs_user_control","paused","succeeded","failed","canceled"],"description":"Where the run is now. `succeeded`, `failed` and `canceled` are terminal. `paused` means a person put the agent on hold: the worker's channels are shut until Resume. It is not `needs_user_control`, which can mean the agent is asking for help or an interrupted hosted run is waiting for explicit continuation. A non-null `recovery` distinguishes the latter.","isRequired":true,"uniqueKey":"state","typeLabel":"enum\u003cstring>"},"stepSeq":{"type":"integer","description":"Metered steps issued so far. One step is one frame served.","isRequired":true,"uniqueKey":"stepSeq","typeLabel":"integer"},"maxSteps":{"type":"integer","description":"The run's step ceiling.","isRequired":true,"uniqueKey":"maxSteps","typeLabel":"integer"},"deadlineAt":{"oneOf":[{"type":"string","format":"date-time","description":"Absolute wall clock deadline, or null when the stored deadline is not a renderable instant. FROZEN while the run is `paused`: the time the agent spends on hold is not charged to the run, and resuming slides this forward by however long the hold lasted. It is null during recovery waiting; `recovery.remainingMs` reports the saved time budget.","isRequired":true,"uniqueKey":"deadlineAt.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","description":"Absolute wall clock deadline, or null when the stored deadline is not a renderable instant. FROZEN while the run is `paused`: the time the agent spends on hold is not charged to the run, and resuming slides this forward by however long the hold lasted. It is null during recovery waiting; `recovery.remainingMs` reports the saved time budget.","isRequired":true,"uniqueKey":"deadlineAt.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"deadlineAt","typeLabel":"string\u003cdate-time> | null"},"createdAt":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"createdAt","typeLabel":"string\u003cdate-time>"},"updatedAt":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"updatedAt","typeLabel":"string\u003cdate-time>"},"workerFirstContactAt":{"oneOf":[{"type":"string","format":"date-time","description":"When a self-hosted worker first reached this run, or null when none ever did. On a `self_hosted` run you supply the worker, and one that stays queued with null here is waiting for it. A `phoneuse` run is driven in process and never sets this.","isRequired":true,"uniqueKey":"workerFirstContactAt.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","description":"When a self-hosted worker first reached this run, or null when none ever did. On a `self_hosted` run you supply the worker, and one that stays queued with null here is waiting for it. A `phoneuse` run is driven in process and never sets this.","isRequired":true,"uniqueKey":"workerFirstContactAt.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"workerFirstContactAt","typeLabel":"string\u003cdate-time> | null"},"initiator":{"type":"object","properties":{"kind":{"type":"string","enum":["api_key","oauth","dev_token","system","unattributed"],"description":"Which credential this was. `system` is PhoneUse itself: a schedule's timer, or PhoneUse driving a run, and `onBehalfOf` then says for whom; it is never a person. `unattributed` means the record cannot say, which is NOT the same as a positive claim that no key was involved: it is what a row written before this field existed reads as.","isRequired":true,"uniqueKey":"initiator.kind","typeLabel":"enum\u003cstring>"},"viaCopilot":{"type":"boolean","description":"Whether a copilot did this on the named person's behalf. The person stays responsible: a label reads like \"Mira Osei via copilot\". ALWAYS PRESENT, and false today on every record, because there is no copilot yet. Present and false says so; an absent field would only mean an older server.","isRequired":true,"uniqueKey":"initiator.viaCopilot","typeLabel":"boolean"},"userId":{"type":"string","description":"The authorization server's subject id of the PERSON, present only when `kind` is `oauth`. It is an id and never a name: resolve it through your own directory. Nothing here stores a name or an email address.","uniqueKey":"initiator.userId","typeLabel":"string"},"apiKeyId":{"type":"string","description":"The key's id, present only when `kind` is `api_key`. The same id `GET /v1/api-keys` lists.","uniqueKey":"initiator.apiKeyId","typeLabel":"string"},"onBehalfOf":{"type":"object","properties":{"kind":{"type":"string","enum":["schedule","user","api_key","dev_token"],"description":"Whose work it was: `schedule` (a timer fired), `user` or `api_key` (PhoneUse drove a run that person or key started), or `dev_token` (the local operator).","isRequired":true,"uniqueKey":"initiator.onBehalfOf.kind","typeLabel":"enum\u003cstring>"},"scheduleId":{"type":"string","description":"The schedule, when `kind` is `schedule`.","uniqueKey":"initiator.onBehalfOf.scheduleId","typeLabel":"string"},"userId":{"type":"string","description":"The person's subject id, when `kind` is `user`. An id, never a name.","uniqueKey":"initiator.onBehalfOf.userId","typeLabel":"string"},"apiKeyId":{"type":"string","description":"The key's id, when `kind` is `api_key`.","uniqueKey":"initiator.onBehalfOf.apiKeyId","typeLabel":"string"}},"required":["kind"],"additionalProperties":false,"description":"Present exactly when `kind` is `system`: the control plane acted, and this says for whom. Never present on any other kind.","uniqueKey":"initiator.onBehalfOf","typeLabel":"object"}},"required":["kind","viaCopilot"],"additionalProperties":false,"description":"WHO. The same shape answers three questions: who took an action (`Receipt.actor`), who is holding a device (`Lease.holder`), and who started a run (`RunView.initiator`). One shape on purpose, so the three can never disagree about what a given credential is called.","isRequired":true,"uniqueKey":"initiator","typeLabel":"object"},"scheduleId":{"oneOf":[{"type":"string","description":"The schedule that started this run, or null when a person or a key did. Present and null rather than absent, so you can tell those apart from an older server that does not say. Schedules were retired, so a run started now is always null here; only an older run can carry an id.","isRequired":true,"uniqueKey":"scheduleId.oneOf.0","typeLabel":"string"},{"type":"null","description":"The schedule that started this run, or null when a person or a key did. Present and null rather than absent, so you can tell those apart from an older server that does not say. Schedules were retired, so a run started now is always null here; only an older run can carry an id.","isRequired":true,"uniqueKey":"scheduleId.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"scheduleId","typeLabel":"string | null"},"pausedAt":{"oneOf":[{"type":"string","format":"date-time","description":"When a person put the run on hold, or null when it is not on hold. Present and null rather than absent, so a consumer can tell \"not on hold\" from an older server that does not report it.","isRequired":true,"uniqueKey":"pausedAt.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","description":"When a person put the run on hold, or null when it is not on hold. Present and null rather than absent, so a consumer can tell \"not on hold\" from an older server that does not report it.","isRequired":true,"uniqueKey":"pausedAt.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"pausedAt","typeLabel":"string\u003cdate-time> | null"},"manualControlUntil":{"oneOf":[{"type":"string","format":"date-time","description":"When the hold ends, or null when the run is not paused. This is the clock that runs while the run is on hold, not `deadlineAt`. Past it, a run nobody resumed is `canceled` with an explanation in `detail`; no new failure reason is used. The name is kept from when a hold was a person's manual control window; a person needs no window to act on the device now.","isRequired":true,"uniqueKey":"manualControlUntil.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","description":"When the hold ends, or null when the run is not paused. This is the clock that runs while the run is on hold, not `deadlineAt`. Past it, a run nobody resumed is `canceled` with an explanation in `detail`; no new failure reason is used. The name is kept from when a hold was a person's manual control window; a person needs no window to act on the device now.","isRequired":true,"uniqueKey":"manualControlUntil.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"manualControlUntil","typeLabel":"string\u003cdate-time> | null"},"lastFrame":{"oneOf":[{"type":"object","description":"The last frame this run was served, or null when it has been served none. On a finished run this is the frame the model's report was written from, because `finish_run` ends the turn and nothing is captured after it, so a reader can put what the model said next to the screen it read that off. `viewport` is the frame's own pixel geometry, which is the coordinate basis it was captured in and not necessarily the device's current size.","properties":{"frameId":{"type":"string","isRequired":true,"uniqueKey":"lastFrame.oneOf.0.frameId","typeLabel":"string"},"viewport":{"type":"object","properties":{"width":{"type":"integer","isRequired":true,"uniqueKey":"lastFrame.oneOf.0.viewport.width","typeLabel":"integer"},"height":{"type":"integer","isRequired":true,"uniqueKey":"lastFrame.oneOf.0.viewport.height","typeLabel":"integer"}},"required":["width","height"],"additionalProperties":false,"isRequired":true,"uniqueKey":"lastFrame.oneOf.0.viewport","typeLabel":"object"}},"required":["frameId","viewport"],"additionalProperties":false,"isRequired":true,"uniqueKey":"lastFrame.oneOf.0","typeLabel":"object"},{"type":"null","description":"The last frame this run was served, or null when it has been served none. On a finished run this is the frame the model's report was written from, because `finish_run` ends the turn and nothing is captured after it, so a reader can put what the model said next to the screen it read that off. `viewport` is the frame's own pixel geometry, which is the coordinate basis it was captured in and not necessarily the device's current size.","properties":{"frameId":{"type":"string"},"viewport":{"type":"object","properties":{"width":{"type":"integer"},"height":{"type":"integer"}},"required":["width","height"],"additionalProperties":false}},"required":["frameId","viewport"],"additionalProperties":false,"isRequired":true,"uniqueKey":"lastFrame.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"lastFrame","typeLabel":"object | null"},"recovery":{"oneOf":[{"type":"object","description":"An interrupted hosted run waiting for explicit continuation, or null. Older servers may omit this field. Progress and remaining budget are preserved; no action is replayed automatically.","properties":{"id":{"type":"string","format":"uuid","description":"This interruption episode. Send it as expectedRecoveryId when continuing.","isRequired":true,"uniqueKey":"recovery.oneOf.0.id","typeLabel":"string\u003cuuid>"},"since":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"recovery.oneOf.0.since","typeLabel":"string\u003cdate-time>"},"remainingMs":{"type":"integer","minimum":0,"maximum":9007199254740991,"isRequired":true,"uniqueKey":"recovery.oneOf.0.remainingMs","typeLabel":"integer"},"blockedReason":{"oneOf":[{"type":"string","enum":[null,"action_unresolved","budget_exhausted"],"description":"A non-null reason prevents continuation. Reading this record does not settle an unresolved action.","isRequired":true,"uniqueKey":"recovery.oneOf.0.blockedReason.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","enum":[null,"action_unresolved","budget_exhausted"],"description":"A non-null reason prevents continuation. Reading this record does not settle an unresolved action.","isRequired":true,"uniqueKey":"recovery.oneOf.0.blockedReason.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recovery.oneOf.0.blockedReason","typeLabel":"enum\u003cstring> | null"}},"required":["id","since","remainingMs","blockedReason"],"additionalProperties":false,"uniqueKey":"recovery.oneOf.0","typeLabel":"object"},{"type":"null","description":"An interrupted hosted run waiting for explicit continuation, or null. Older servers may omit this field. Progress and remaining budget are preserved; no action is replayed automatically.","properties":{"id":{"type":"string","format":"uuid","description":"This interruption episode. Send it as expectedRecoveryId when continuing."},"since":{"type":"string","format":"date-time"},"remainingMs":{"type":"integer","minimum":0,"maximum":9007199254740991},"blockedReason":{"oneOf":[{"type":"string","enum":[null,"action_unresolved","budget_exhausted"],"description":"A non-null reason prevents continuation. Reading this record does not settle an unresolved action."},{"type":"null","enum":[null,"action_unresolved","budget_exhausted"],"description":"A non-null reason prevents continuation. Reading this record does not settle an unresolved action."}]}},"required":["id","since","remainingMs","blockedReason"],"additionalProperties":false,"uniqueKey":"recovery.oneOf.1","typeLabel":"null"}],"uniqueKey":"recovery","typeLabel":"object | null"},"progress":{"type":"object","properties":{"revision":{"type":"integer","minimum":1,"maximum":9007199254740991,"isRequired":true,"uniqueKey":"progress.revision","typeLabel":"integer"},"goalRevision":{"type":"integer","minimum":1,"maximum":9007199254740991,"isRequired":true,"uniqueKey":"progress.goalRevision","typeLabel":"integer"},"completedStepIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200,"uniqueKey":"progress.completedStepIds.items.[INDEX]","typeLabel":"string"},"minItems":0,"maxItems":128,"isRequired":true,"uniqueKey":"progress.completedStepIds","typeLabel":"string[]"},"remainingStepIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200,"uniqueKey":"progress.remainingStepIds.items.[INDEX]","typeLabel":"string"},"minItems":0,"maxItems":128,"isRequired":true,"uniqueKey":"progress.remainingStepIds","typeLabel":"string[]"},"unresolvedOperations":{"type":"array","items":{"type":"object","properties":{"semanticStepId":{"type":"string","minLength":1,"maxLength":200,"isRequired":true,"uniqueKey":"progress.unresolvedOperations.items.[INDEX].semanticStepId","typeLabel":"string"},"operationRef":{"type":"string","minLength":1,"maxLength":200,"isRequired":true,"uniqueKey":"progress.unresolvedOperations.items.[INDEX].operationRef","typeLabel":"string"},"state":{"enum":["prepared","unknown","confirmed","failed"],"type":"string","isRequired":true,"uniqueKey":"progress.unresolvedOperations.items.[INDEX].state","typeLabel":"enum\u003cstring>"}},"required":["semanticStepId","operationRef","state"],"additionalProperties":false,"uniqueKey":"progress.unresolvedOperations.items.[INDEX]","typeLabel":"object"},"minItems":0,"maxItems":128,"isRequired":true,"uniqueKey":"progress.unresolvedOperations","typeLabel":"object[]"},"goalChecks":{"type":"array","items":{"type":"object","properties":{"checkId":{"type":"string","minLength":1,"maxLength":200,"isRequired":true,"uniqueKey":"progress.goalChecks.items.[INDEX].checkId","typeLabel":"string"},"verdict":{"enum":["confirmed","unconfirmed","contradicted"],"type":"string","isRequired":true,"uniqueKey":"progress.goalChecks.items.[INDEX].verdict","typeLabel":"enum\u003cstring>"},"reason":{"enum":[null,"matched","missing_label","ambiguous_label","unavailable","stale_or_mismatched"],"isRequired":true,"uniqueKey":"progress.goalChecks.items.[INDEX].reason","typeLabel":"any"},"proof":{"oneOf":[{"type":"object","required":["target","generation","capturedAtMs","frameRef","frameHash","checkerVersion","source"],"properties":{"target":{"type":"object","properties":{"deviceId":{"type":"string","minLength":1,"maxLength":200,"isRequired":true,"uniqueKey":"progress.goalChecks.items.[INDEX].proof.oneOf.0.target.deviceId","typeLabel":"string"},"incarnation":{"type":"string","minLength":1,"maxLength":200,"isRequired":true,"uniqueKey":"progress.goalChecks.items.[INDEX].proof.oneOf.0.target.incarnation","typeLabel":"string"}},"required":["deviceId","incarnation"],"additionalProperties":false,"isRequired":true,"uniqueKey":"progress.goalChecks.items.[INDEX].proof.oneOf.0.target","typeLabel":"object"},"generation":{"type":"integer","minimum":1,"maximum":9007199254740991,"isRequired":true,"uniqueKey":"progress.goalChecks.items.[INDEX].proof.oneOf.0.generation","typeLabel":"integer"},"capturedAtMs":{"type":"integer","minimum":0,"maximum":9007199254740991,"isRequired":true,"uniqueKey":"progress.goalChecks.items.[INDEX].proof.oneOf.0.capturedAtMs","typeLabel":"integer"},"frameRef":{"type":"string","minLength":1,"maxLength":2048,"isRequired":true,"uniqueKey":"progress.goalChecks.items.[INDEX].proof.oneOf.0.frameRef","typeLabel":"string"},"frameHash":{"type":"string","pattern":"^[a-f0-9]{64}$","isRequired":true,"uniqueKey":"progress.goalChecks.items.[INDEX].proof.oneOf.0.frameHash","typeLabel":"string"},"checkerVersion":{"type":"string","minLength":1,"maxLength":200,"isRequired":true,"uniqueKey":"progress.goalChecks.items.[INDEX].proof.oneOf.0.checkerVersion","typeLabel":"string"},"source":{"const":"verified_frame_ocr","isRequired":true,"uniqueKey":"progress.goalChecks.items.[INDEX].proof.oneOf.0.source","typeLabel":"any"}},"additionalProperties":false,"isRequired":true,"uniqueKey":"progress.goalChecks.items.[INDEX].proof.oneOf.0","typeLabel":"object"},{"type":"null","isRequired":true,"uniqueKey":"progress.goalChecks.items.[INDEX].proof.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"progress.goalChecks.items.[INDEX].proof","typeLabel":"object | null"}},"required":["checkId","verdict","reason","proof"],"additionalProperties":false,"uniqueKey":"progress.goalChecks.items.[INDEX]","typeLabel":"object"},"minItems":0,"maxItems":32,"isRequired":true,"uniqueKey":"progress.goalChecks","typeLabel":"object[]"},"verifiedOutcome":{"type":"boolean","isRequired":true,"uniqueKey":"progress.verifiedOutcome","typeLabel":"boolean"}},"required":["revision","goalRevision","completedStepIds","remainingStepIds","unresolvedOperations","goalChecks","verifiedOutcome"],"additionalProperties":false,"description":"Optional original confirmed-plan progress from a fresh committed read. Legacy runs have no synthesized proof; historical facts grant no new effects.","uniqueKey":"progress","typeLabel":"object"},"reason":{"type":"string","enum":["worker_reported_failure","budget_exhausted","deadline_exceeded","canceled_by_caller","lease_lost","interrupted_by_restart"],"description":"Why the run ended, when it did not simply succeed.","uniqueKey":"reason","typeLabel":"enum\u003cstring>"},"detail":{"type":"string","description":"Free text about how the run ended. A worker's own report, or, when the run hit its deadline, the control plane's explanation of which kind of timeout it was.","uniqueKey":"detail","typeLabel":"string"}},"required":["runId","agentRunId","deviceId","goal","executor","state","stepSeq","maxSteps","deadlineAt","createdAt","updatedAt","workerFirstContactAt","initiator","pausedAt","manualControlUntil","scheduleId","lastFrame"],"additionalProperties":false,"description":"The public projection of a run, and who started it. The run token is deliberately absent: it is returned once, when the run is started, and never again.","uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"runId":"\u003cstring>","agentRunId":"\u003cstring>","deviceId":"\u003cstring>","goal":"\u003cstring>","executor":"phoneuse","state":"queued","stepSeq":123,"maxSteps":123,"deadlineAt":"2023-11-07T05:31:56Z","createdAt":"2023-11-07T05:31:56Z","updatedAt":"2023-11-07T05:31:56Z","workerFirstContactAt":"2023-11-07T05:31:56Z","initiator":{"kind":"api_key","viaCopilot":true,"userId":"\u003cstring>","apiKeyId":"\u003cstring>","onBehalfOf":{"kind":"schedule","scheduleId":"\u003cstring>","userId":"\u003cstring>","apiKeyId":"\u003cstring>"}},"scheduleId":"\u003cstring>","pausedAt":"2023-11-07T05:31:56Z","manualControlUntil":"2023-11-07T05:31:56Z","lastFrame":{"frameId":"\u003cstring>","viewport":{"width":123,"height":123}},"recovery":{"id":"3c90c3cc-0d44-4b50-8888-8dd25736052a","since":"2023-11-07T05:31:56Z","remainingMs":4503599627370495,"blockedReason":null},"progress":{"revision":4503599627370496,"goalRevision":4503599627370496,"completedStepIds":["\u003cstring>"],"remainingStepIds":["\u003cstring>"],"unresolvedOperations":[{"semanticStepId":"\u003cstring>","operationRef":"\u003cstring>","state":"prepared"}],"goalChecks":[{"checkId":"\u003cstring>","verdict":"confirmed","reason":null,"proof":{"target":{"deviceId":"\u003cstring>","incarnation":"\u003cstring>"},"generation":4503599627370496,"capturedAtMs":4503599627370495,"frameRef":"\u003cstring>","frameHash":"\u003cstring>","checkerVersion":"\u003cstring>","source":"verified_frame_ocr"}}],"verifiedOutcome":true},"reason":"worker_reported_failure","detail":"\u003cstring>"}}},"exampleType":"generated"}},"exampleType":"generated"},"fcd55eee-c5aa-4ff0-9cb0-70bad1671786":{"description":"`waitMs` was not an integer from 0 to 25000, or `sinceState` was not a run state. Or the id was not printable text of the allowed length.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["backend_resolution_failed","backend_not_implemented","device_unavailable","device_disconnected","lease_mismatch","lease_required","capability_unsupported","invalid_argument","backend_command_failed","idempotency_conflict","action_outcome_unknown","stale_frame","internal_error","unauthorized","permission_denied","run_not_found","frame_not_found","device_busy","admission_unavailable","checkout_unavailable","checkout_customer_balance","checkout_in_progress","quote_changed","payment_in_progress","out_of_stock","wrong_state","instance_not_served","reverification_required","not_found","receipt_not_found","rate_limited","payload_too_large","origin_not_allowed","api_key_from_browser_origin","key_predates_instance_attribution","org_not_served_by_instance","tenant_binding_unavailable","tenant_binding_unsettled","fleet_at_capacity","forbidden","service_unavailable","invalid_signature","invalid_event","not_settled"],"description":"The closed set of codes this service answers with on purpose, on MCP tools and REST alike (D152). What each one means and when you get it is on the errors page.","isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"A human readable summary. Do not branch on it, branch on `code`.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"retryable":{"type":"boolean","description":"Whether re-issuing the same call unchanged is meaningful. It is a property of the occurrence, not of the code, so read the field rather than inferring it.","uniqueKey":"error.retryable","typeLabel":"boolean"}},"required":["code","message"],"additionalProperties":true,"description":"Specific errors add their own fields, such as `deviceId`, `reason` or `capability`. Read the ones you branch on and ignore the rest.","isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"additionalProperties":false,"description":"The control surface error envelope. Every non 2xx JSON body on this surface has this shape.","uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"backend_resolution_failed","message":"\u003cstring>","retryable":true}}}},"exampleType":"generated"}},"exampleType":"generated"},"e1a49f53-98bb-4737-9996-fe1032dcfcd6":{"description":"No credential, or one that was refused.","headers":{"WWW-Authenticate":{"description":"A bearer challenge. On a hosted deployment it names the metadata document to discover the authorization server from, and it adds `error=\"invalid_token\"` when a credential was presented and rejected.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","const":"unauthorized","description":"Always `unauthorized` on this response.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"reason":{"type":"string","enum":["missing_credentials","malformed_credentials","invalid_token","token_expired","wrong_audience","missing_org","missing_org_role","unknown_key","revoked_key","expired_key"],"description":"The closed set of ways authentication can fail.","isRequired":true,"uniqueKey":"error.reason","typeLabel":"enum\u003cstring>"},"hint":{"type":"string","description":"A next step in prose, on the reasons where there is one to give: `revoked_key`, `expired_key`, `missing_org_role`, and `invalid_token` when the account is not a member of the named organization. Absent otherwise, so branch on `reason` and show this if it is there.","uniqueKey":"error.hint","typeLabel":"string"}},"required":["code","reason"],"additionalProperties":false,"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"additionalProperties":false,"description":"A refused credential. `unknown_key` covers both a keyId nobody has and a secret that does not match, because telling those apart would enumerate keys for you. Revocation and expiry are distinguishable, since you owned that key.","uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthorized","reason":"missing_credentials","hint":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"da55db36-43a1-4875-8bcf-3a01cd56b90c":{"description":"Authenticated, but this credential does not carry what the call needs. Every authenticated endpoint can also answer `org_not_served_by_instance` here: the organization named by the credential belongs to a different authentication instance, so re-authenticating will not help.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["backend_resolution_failed","backend_not_implemented","device_unavailable","device_disconnected","lease_mismatch","lease_required","capability_unsupported","invalid_argument","backend_command_failed","idempotency_conflict","action_outcome_unknown","stale_frame","internal_error","unauthorized","permission_denied","run_not_found","frame_not_found","device_busy","admission_unavailable","checkout_unavailable","checkout_customer_balance","checkout_in_progress","quote_changed","payment_in_progress","out_of_stock","wrong_state","instance_not_served","reverification_required","not_found","receipt_not_found","rate_limited","payload_too_large","origin_not_allowed","api_key_from_browser_origin","key_predates_instance_attribution","org_not_served_by_instance","tenant_binding_unavailable","tenant_binding_unsettled","fleet_at_capacity","forbidden","service_unavailable","invalid_signature","invalid_event","not_settled"],"description":"The closed set of codes this service answers with on purpose, on MCP tools and REST alike (D152). What each one means and when you get it is on the errors page.","isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"A human readable summary. Do not branch on it, branch on `code`.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"retryable":{"type":"boolean","description":"Whether re-issuing the same call unchanged is meaningful. It is a property of the occurrence, not of the code, so read the field rather than inferring it.","uniqueKey":"error.retryable","typeLabel":"boolean"}},"required":["code","message"],"additionalProperties":true,"description":"Specific errors add their own fields, such as `deviceId`, `reason` or `capability`. Read the ones you branch on and ignore the rest.","isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"additionalProperties":false,"description":"The control surface error envelope. Every non 2xx JSON body on this surface has this shape.","uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"backend_resolution_failed","message":"\u003cstring>","retryable":true}}}},"exampleType":"generated"}},"exampleType":"generated"},"73e23f92-4c17-435b-8c55-abe06b56b93b":{"description":"No run under this id that your org can see. A run owned by another org answers exactly the same way, so this is not an existence oracle.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["backend_resolution_failed","backend_not_implemented","device_unavailable","device_disconnected","lease_mismatch","lease_required","capability_unsupported","invalid_argument","backend_command_failed","idempotency_conflict","action_outcome_unknown","stale_frame","internal_error","unauthorized","permission_denied","run_not_found","frame_not_found","device_busy","admission_unavailable","checkout_unavailable","checkout_customer_balance","checkout_in_progress","quote_changed","payment_in_progress","out_of_stock","wrong_state","instance_not_served","reverification_required","not_found","receipt_not_found","rate_limited","payload_too_large","origin_not_allowed","api_key_from_browser_origin","key_predates_instance_attribution","org_not_served_by_instance","tenant_binding_unavailable","tenant_binding_unsettled","fleet_at_capacity","forbidden","service_unavailable","invalid_signature","invalid_event","not_settled"],"description":"The closed set of codes this service answers with on purpose, on MCP tools and REST alike (D152). What each one means and when you get it is on the errors page.","isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"A human readable summary. Do not branch on it, branch on `code`.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"retryable":{"type":"boolean","description":"Whether re-issuing the same call unchanged is meaningful. It is a property of the occurrence, not of the code, so read the field rather than inferring it.","uniqueKey":"error.retryable","typeLabel":"boolean"}},"required":["code","message"],"additionalProperties":true,"description":"Specific errors add their own fields, such as `deviceId`, `reason` or `capability`. Read the ones you branch on and ignore the rest.","isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"additionalProperties":false,"description":"The control surface error envelope. Every non 2xx JSON body on this surface has this shape.","uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"backend_resolution_failed","message":"\u003cstring>","retryable":true}}}},"exampleType":"generated"}},"exampleType":"generated"},"e363f228-6c58-43af-a2cb-c80395c48a80":{"description":"Over the request budget for this caller. Hosted deployments only. Which budget applied depends on whether this request carried an `Authorization` header, not on which endpoint it was aimed at. Wait `Retry-After` seconds and retry the same request: the refusal happens before any work, so nothing was partially applied. See /api/rate-limits.","headers":{"Retry-After":{"description":"Whole seconds until one request is available again. Computed from the caller's own remaining allowance, not a fixed constant.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"The budget in effect for this caller class, in requests per minute.","schema":{"type":"string"}},"RateLimit-Remaining":{"description":"Whole requests that were still available when this request was admitted. Zero on a 429.","schema":{"type":"string"}},"RateLimit-Reset":{"description":"Seconds until the allowance is back to full. Longer than `Retry-After`, which is the wait for a single request.","schema":{"type":"string"}},"RateLimit-Policy":{"description":"The budget and its window, as `\u003climit>;w=60`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","const":"rate_limited","description":"Always `rate_limited` on this response.","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","description":"A human readable summary. The numbers are in the headers, not in here.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"additionalProperties":false,"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"additionalProperties":false,"description":"Over the request budget. Raised by the rate limiter before any handler runs, which is why its code is not one of the action codes: nothing was attempted, so no action failed.","uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"rate_limited","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"1be104d5-c436-4e4f-ae36-651294c1d718":{"description":"The authentication backend could not be reached. The service fails closed: an infrastructure fault is refused, never waved through.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["backend_resolution_failed","backend_not_implemented","device_unavailable","device_disconnected","lease_mismatch","lease_required","capability_unsupported","invalid_argument","backend_command_failed","idempotency_conflict","action_outcome_unknown","stale_frame","internal_error","unauthorized","permission_denied","run_not_found","frame_not_found","device_busy","admission_unavailable","checkout_unavailable","checkout_customer_balance","checkout_in_progress","quote_changed","payment_in_progress","out_of_stock","wrong_state","instance_not_served","reverification_required","not_found","receipt_not_found","rate_limited","payload_too_large","origin_not_allowed","api_key_from_browser_origin","key_predates_instance_attribution","org_not_served_by_instance","tenant_binding_unavailable","tenant_binding_unsettled","fleet_at_capacity","forbidden","service_unavailable","invalid_signature","invalid_event","not_settled"],"description":"The closed set of codes this service answers with on purpose, on MCP tools and REST alike (D152). What each one means and when you get it is on the errors page.","isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"A human readable summary. Do not branch on it, branch on `code`.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"retryable":{"type":"boolean","description":"Whether re-issuing the same call unchanged is meaningful. It is a property of the occurrence, not of the code, so read the field rather than inferring it.","uniqueKey":"error.retryable","typeLabel":"boolean"}},"required":["code","message"],"additionalProperties":true,"description":"Specific errors add their own fields, such as `deviceId`, `reason` or `capability`. Read the ones you branch on and ignore the rest.","isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"additionalProperties":false,"description":"The control surface error envelope. Every non 2xx JSON body on this surface has this shape.","uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"backend_resolution_failed","message":"\u003cstring>","retryable":true}}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{"edc6a97f-6382-4ebd-b9df-7f5c5e17fd48":{"bearerAuth":{"type":"http","scheme":"bearer","description":"The control surface credential. Send `Authorization: Bearer \u003ctoken>`.\n\nTwo kinds of token are accepted and they are told apart by shape, not by a separate header. A token beginning `pbk_` or `puk_` is an org scoped API key, whose public half and secret half are generated together and of which only a hash of the secret is ever stored; anything else is treated as an OAuth 2.1 access token and verified against the authorization server's keys.\n\nBoth resolve to the same context: an org, a principal and a set of scopes. Nothing downstream branches on which channel you used, with one deliberate exception, key management, which requires a signed-in person so that a key can never mint another key.\n\nScopes are enforced when MCP tools are REGISTERED rather than when they are called, so a tool your credential cannot use is absent from `tools/list` rather than refused mid gesture.","scopes":[],"schemeName":"bearerAuth"}}},"servers":{"0b8b9ab5-c46d-4bb8-88b0-6eeb0d5654ea":{"url":"{origin}","description":"Your control plane origin.","variables":{"origin":{"default":"https://mcp.phoneuse.com","enum":["https://mcp.phoneuse.com","http://127.0.0.1:8788"],"description":"The hosted deployment serves the public origin its metadata document advertises, and that is the default here. Select the loopback entry instead when you are running a local checkout, which serves the port `PORT` names."}}}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","scheme":"bearer","description":"The control surface credential. Send `Authorization: Bearer \u003ctoken>`.\n\nTwo kinds of token are accepted and they are told apart by shape, not by a separate header. A token beginning `pbk_` or `puk_` is an org scoped API key, whose public half and secret half are generated together and of which only a hash of the secret is ever stored; anything else is treated as an OAuth 2.1 access token and verified against the authorization server's keys.\n\nBoth resolve to the same context: an org, a principal and a set of scopes. Nothing downstream branches on which channel you used, with one deliberate exception, key management, which requires a signed-in person so that a key can never mint another key.\n\nScopes are enforced when MCP tools are REGISTERED rather than when they are called, so a tool your credential cannot use is absent from `tools/list` rather than refused mid gesture.","scopes":[],"schemeName":"bearerAuth"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"The control surface credential. Send `Authorization: Bearer \u003ctoken>`.\n\nTwo kinds of token are accepted and they are told apart by shape, not by a separate header. A token beginning `pbk_` or `puk_` is an org scoped API key, whose public half and secret half are generated together and of which only a hash of the secret is ever stored; anything else is treated as an OAuth 2.1 access token and verified against the authorization server's keys.\n\nBoth resolve to the same context: an org, a principal and a set of scopes. Nothing downstream branches on which channel you used, with one deliberate exception, key management, which requires a signed-in person so that a key can never mint another key.\n\nScopes are enforced when MCP tools are REGISTERED rather than when they are called, so a tool your credential cannot use is absent from `tools/list` rather than refused mid gesture.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"bearerAuth","name":"Authorization"}],"title":"bearerAuth"}]},"originalFileLocation":"api/openapi.json"},"subdomain":"phonebase","siteName":"PhoneUse","title":"Read a run, optionally waiting for it to move - PhoneUse","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-30T04:26:06.219Z","originalFileLocation":"api/endpoints/runs/read-a-run-optionally-waiting-for-it-to-move.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=\"light\"}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=\"Returns the run as it is now. With waitMs it waits for the state to leave sinceState and returns as soon as it does, or at the deadline with whatever the state is then. It never hangs: the transport is stateless and there is no push channel. EITHER ID WORKS HERE. Send the runId POST /v1/runs returned, or the run\u0026#x27;s agentRunId: the id every receipt the run produced carries and the one a permalink is built on. An id starting run_ is read as an agentRunId, anything else as a runId. Both answer with the same run through the same checks, waitMs included. The writes below take a runId only. This returns the run only. Its action trail is a separate, paged resource, GET /v1/receipts?agentRunId=..., and it is not folded in here: it is a paged collection with its own cursor and its own retention. This route applies the calling key\u0026#x27;s device narrowing: a run on a device your key cannot address is 404, the same 404 an unknown id gets.\">\u003cmeta data-mint-head name=\"application-name\" content=\"PhoneUse\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/phonebase/kWipq_KjnF--s93A/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/phonebase/kWipq_KjnF--s93A/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/phonebase/kWipq_KjnF--s93A/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/phonebase/kWipq_KjnF--s93A/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/phonebase/kWipq_KjnF--s93A/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/phonebase/kWipq_KjnF--s93A/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/phonebase/kWipq_KjnF--s93A/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/phonebase/kWipq_KjnF--s93A/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/phonebase/kWipq_KjnF--s93A/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Read a run, optionally waiting for it to move - PhoneUse\">\u003cmeta data-mint-head property=\"og:description\" content=\"Returns the run as it is now. With waitMs it waits for the state to leave sinceState and returns as soon as it does, or at the deadline with whatever the state is then. It never hangs: the transport is stateless and there is no push channel. EITHER ID WORKS HERE. Send the runId POST /v1/runs returned, or the run\u0026#x27;s agentRunId: the id every receipt the run produced carries and the one a permalink is built on. An id starting run_ is read as an agentRunId, anything else as a runId. Both answer with the same run through the same checks, waitMs included. The writes below take a runId only. This returns the run only. Its action trail is a separate, paged resource, GET /v1/receipts?agentRunId=..., and it is not folded in here: it is a paged collection with its own cursor and its own retention. This route applies the calling key\u0026#x27;s device narrowing: a run on a device your key cannot address is 404, the same 404 an unknown id gets.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"PhoneUse\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.phoneuse.com/api/endpoints/runs/read-a-run-optionally-waiting-for-it-to-move\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://phonebase.mintlify.site/_mintlify/api/og/v2?division=Runs\u0026amp;title=Read+a+run%2C+optionally+waiting+for+it+to+move\u0026amp;description=Returns+the+run+as+it+is+now.+With+%60waitMs%60+it+waits+for+the+state+to+leave+%60sinceState%60+and+returns+as+soon+as+it+does%2C+or+at+the+deadline+with+whatever+the+st\u0026amp;theme=370fb2999dfbb8f85a217f41\u0026amp;signature=3cdb9dec8f34e8e5ea1ac5e7f4c5c42dc86ad21079e9683b3c7d2542f81876bf\">\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=\"Read a run, optionally waiting for it to move - PhoneUse\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Returns the run as it is now. With waitMs it waits for the state to leave sinceState and returns as soon as it does, or at the deadline with whatever the state is then. It never hangs: the transport is stateless and there is no push channel. EITHER ID WORKS HERE. Send the runId POST /v1/runs returned, or the run\u0026#x27;s agentRunId: the id every receipt the run produced carries and the one a permalink is built on. An id starting run_ is read as an agentRunId, anything else as a runId. Both answer with the same run through the same checks, waitMs included. The writes below take a runId only. This returns the run only. Its action trail is a separate, paged resource, GET /v1/receipts?agentRunId=..., and it is not folded in here: it is a paged collection with its own cursor and its own retention. This route applies the calling key\u0026#x27;s device narrowing: a run on a device your key cannot address is 404, the same 404 an unknown id gets.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://phonebase.mintlify.site/_mintlify/api/og/v2?division=Runs\u0026amp;title=Read+a+run%2C+optionally+waiting+for+it+to+move\u0026amp;description=Returns+the+run+as+it+is+now.+With+%60waitMs%60+it+waits+for+the+state+to+leave+%60sinceState%60+and+returns+as+soon+as+it+does%2C+or+at+the+deadline+with+whatever+the+st\u0026amp;theme=370fb2999dfbb8f85a217f41\u0026amp;signature=3cdb9dec8f34e8e5ea1ac5e7f4c5c42dc86ad21079e9683b3c7d2542f81876bf\">\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=\"/mintlify-assets/_mintlify/favicons/phonebase/kWipq_KjnF--s93A/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"PhoneUse\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#0c6b4f\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.phoneuse.com/api/endpoints/runs/read-a-run-optionally-waiting-for-it-to-move\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api/endpoints/runs/read-a-run-optionally-waiting-for-it-to-move.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.phoneuse.com/#organization\",\"name\":\"PhoneUse\",\"url\":\"https://docs.phoneuse.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/phonebase/asSC9ooLxq3ce7AH/images/logo-light.svg?fit=max\u0026auto=format\u0026n=asSC9ooLxq3ce7AH\u0026q=85\u0026s=797a832db8f0e271d5dbd6beba29a27b\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.phoneuse.com#website\",\"name\":\"PhoneUse\",\"url\":\"https://docs.phoneuse.com\",\"publisher\":{\"@id\":\"https://docs.phoneuse.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.phoneuse.com/api/endpoints/runs/read-a-run-optionally-waiting-for-it-to-move#webpage\",\"url\":\"https://docs.phoneuse.com/api/endpoints/runs/read-a-run-optionally-waiting-for-it-to-move\",\"name\":\"Read a run, optionally waiting for it to move\",\"description\":\"Returns the run as it is now. With waitMs it waits for the state to leave sinceState and returns as soon as it does, or at the deadline with whatever the state is then. It never hangs: the transport is stateless and there is no push channel. EITHER ID WORKS HERE. Send the runId POST /v1/runs returned, or the run's agentRunId: the id every receipt the run produced carries and the one a permalink is built on. An id starting run_ is read as an agentRunId, anything else as a runId. Both answer with the same run through the same checks, waitMs included. The writes below take a runId only. This returns the run only. Its action trail is a separate, paged resource, GET /v1/receipts?agentRunId=..., and it is not folded in here: it is a paged collection with its own cursor and its own retention. This route applies the calling key's device narrowing: a run on a device your key cannot address is 404, the same 404 an unknown id gets.\",\"dateModified\":\"2026-10-30T04:26:06.219Z\",\"isPartOf\":{\"@id\":\"https://docs.phoneuse.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.phoneuse.com/api/endpoints/runs/read-a-run-optionally-waiting-for-it-to-move#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.phoneuse.com/api/endpoints/runs/read-a-run-optionally-waiting-for-it-to-move#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Endpoints\",\"item\":\"https://docs.phoneuse.com/api/endpoints/health/check-that-the-service-is-up\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Runs\",\"item\":\"https://docs.phoneuse.com/api/endpoints/runs/get-a-short-lived-url-for-one-archived-frame\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Read a run, optionally waiting for it to move\",\"item\":\"https://docs.phoneuse.com/api/endpoints/runs/read-a-run-optionally-waiting-for-it-to-move\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.phoneuse.com/api/endpoints/runs/read-a-run-optionally-waiting-for-it-to-move#apireference\",\"headline\":\"Read a run, optionally waiting for it to move\",\"name\":\"Read a run, optionally waiting for it to move\",\"description\":\"Returns the run as it is now. With waitMs it waits for the state to leave sinceState and returns as soon as it does, or at the deadline with whatever the state is then. It never hangs: the transport is stateless and there is no push channel. EITHER ID WORKS HERE. Send the runId POST /v1/runs returned, or the run's agentRunId: the id every receipt the run produced carries and the one a permalink is built on. An id starting run_ is read as an agentRunId, anything else as a runId. Both answer with the same run through the same checks, waitMs included. The writes below take a runId only. This returns the run only. Its action trail is a separate, paged resource, GET /v1/receipts?agentRunId=..., and it is not folded in here: it is a paged collection with its own cursor and its own retention. This route applies the calling key's device narrowing: a run on a device your key cannot address is 404, the same 404 an unknown id gets.\",\"url\":\"https://docs.phoneuse.com/api/endpoints/runs/read-a-run-optionally-waiting-for-it-to-move\",\"mainEntityOfPage\":{\"@id\":\"https://docs.phoneuse.com/api/endpoints/runs/read-a-run-optionally-waiting-for-it-to-move#webpage\"},\"dateModified\":\"2026-10-30T04:26:06.219Z\",\"publisher\":{\"@id\":\"https://docs.phoneuse.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.phoneuse.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"PhoneUse\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"PhoneUse\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api/endpoints/runs/read-a-run-optionally-waiting-for-it-to-move.md","siteName":"PhoneUse","nav":{"global":null,"tabs":[{"tab":"Docs","pages":[{"title":"Docs","href":""}]},{"tab":"API","groups":[{"group":"Overview","pages":[{"title":"API overview","href":"/api"},{"title":"Versioning and compatibility","href":"/api/versioning"},{"title":"Rate limits","href":"/api/rate-limits"}]},{"group":"Endpoints","pages":[{"group":"Health","pages":[{"title":"Check that the service is up","deprecated":null,"version":null,"openapi":"/api/openapi.json get /healthz","href":"/api/endpoints/health/check-that-the-service-is-up"}]},{"group":"Device surface","pages":[{"title":"Check the run's device channel","deprecated":null,"version":null,"openapi":"/api/openapi.json get /vrx/{runToken}/v1/health","href":"/api/endpoints/device-surface/check-the-runs-device-channel"},{"title":"List the run's device","deprecated":null,"version":null,"openapi":"/api/openapi.json get /vrx/{runToken}/v1/devices","href":"/api/endpoints/device-surface/list-the-runs-device"},{"title":"Fetch a frame","deprecated":null,"version":null,"openapi":"/api/openapi.json get /vrx/{runToken}/v1/devices/{deviceId}/screenshot","href":"/api/endpoints/device-surface/fetch-a-frame"},{"title":"Report the run's outcome","deprecated":null,"version":null,"openapi":"/api/openapi.json post /vrx/{runToken}/v1/report","href":"/api/endpoints/device-surface/report-the-runs-outcome"},{"title":"Act on the device","deprecated":null,"version":null,"openapi":"/api/openapi.json post /vrx/{runToken}/v1/devices/{deviceId}/actions","href":"/api/endpoints/device-surface/act-on-the-device"}]},{"group":"MCP","pages":[{"title":"Why there is no event stream","deprecated":null,"version":null,"openapi":"/api/openapi.json get /mcp","href":"/api/endpoints/mcp/why-there-is-no-event-stream"},{"title":"Send a JSON-RPC request","deprecated":null,"version":null,"openapi":"/api/openapi.json post /mcp","href":"/api/endpoints/mcp/send-a-json-rpc-request"},{"title":"Why there is no session to end","deprecated":null,"version":null,"openapi":"/api/openapi.json delete /mcp","href":"/api/endpoints/mcp/why-there-is-no-session-to-end"}]},{"group":"Apps","pages":[{"title":"Discover visible devices and authoritative application scopes","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/app-library/device-capabilities","href":"/api/endpoints/apps/discover-visible-devices-and-authoritative-application-scopes"},{"title":"Read last confirmed phone apps","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/app-library/inventory","href":"/api/endpoints/apps/read-last-confirmed-phone-apps"},{"title":"Request bounded read-only application checks","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/app-library/inventory/refreshes","href":"/api/endpoints/apps/request-bounded-read-only-application-checks"},{"title":"Read application-check progress","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/app-library/inventory/refreshes/{refreshId}","href":"/api/endpoints/apps/read-application-check-progress"},{"title":"Read per-device check outcomes","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/app-library/inventory/refreshes/{refreshId}/results","href":"/api/endpoints/apps/read-per-device-check-outcomes"},{"title":"Recover a lost mutation response by original key","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/app-library/requests/{requestKey}","href":"/api/endpoints/apps/recover-a-lost-mutation-response-by-original-key"},{"title":"List installable apps","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/app-store/catalog","href":"/api/endpoints/apps/list-installable-apps"},{"title":"Read installation history","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/app-store/installations","href":"/api/endpoints/apps/read-installation-history"},{"title":"Install an app","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/app-store/installations","href":"/api/endpoints/apps/install-an-app"},{"title":"Recover an app installation","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/app-store/installations/by-request/{requestKey}","href":"/api/endpoints/apps/recover-an-app-installation"},{"title":"Check an app installation","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/app-store/installations/{installationId}","href":"/api/endpoints/apps/check-an-app-installation"},{"title":"Check an app installation again","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/app-store/installations/{installationId}/recheck","href":"/api/endpoints/apps/check-an-app-installation-again"},{"title":"Skip checking an unconfirmed installation","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/app-store/installations/{installationId}/skip","href":"/api/endpoints/apps/skip-checking-an-unconfirmed-installation"},{"title":"Read a phone's install queue","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/app-store/queue","href":"/api/endpoints/apps/read-a-phones-install-queue"},{"title":"Add an app to a phone's install queue","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/app-store/queue","href":"/api/endpoints/apps/add-an-app-to-a-phones-install-queue"},{"title":"Recover a queued app by its request key","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/app-store/queue/by-request/{requestKey}","href":"/api/endpoints/apps/recover-a-queued-app-by-its-request-key"},{"title":"Remove a waiting app from a phone's queue","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/app-store/queue/{entryId}/remove","href":"/api/endpoints/apps/remove-a-waiting-app-from-a-phones-queue"},{"title":"Pause or resume a phone's install queue","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/app-store/queue/pause","href":"/api/endpoints/apps/pause-or-resume-a-phones-install-queue"}]},{"group":"Runs","pages":[{"title":"Get a short-lived URL for one archived frame","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/frames/{frameId}","href":"/api/endpoints/runs/get-a-short-lived-url-for-one-archived-frame"},{"title":"List your runs","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/runs","href":"/api/endpoints/runs/list-your-runs"},{"title":"Start a run on a device","description":"Hand one device your organisation holds to a run with a goal and a budget. Your organisation must already hold it: starting a run is permission to let a loop act for you, not permission to take the device, and this route is the one place that difference is visible (a gesture DOES take).\n\n`executor` says who drives it. `phoneuse` runs it for you and returns no url. `self_hosted` means your own worker drives it, and the response then carries the run scoped device surface url exactly once: treat it as a credential and give it to one worker only. Left out, it is `self_hosted` for an API key and `phoneuse` for a signed-in person. Your credential needs both `runs:start` and `devices:act`.","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/runs","href":"/api/endpoints/runs/start-a-run-on-a-device"},{"title":"Read a run, optionally waiting for it to move","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/runs/{runId}","href":"/api/endpoints/runs/read-a-run-optionally-waiting-for-it-to-move"},{"title":"Put a run on hold","description":"Suspends the agent. The run moves to `paused`, the worker's channels are shut until Resume (it is served no frames and its actions are refused), its deadline FREEZES, and the run's lease slides to a fresh ten minute window so the hold has one. The worker's steps are untouched: resuming carries on from the current screen rather than redoing what is already done.\n\nYou do not need this to act on the device. A signed-in person drives a device beside a running agent through `POST /v1/devices/{deviceId}/actions` without naming a lease, and the agent is informed of what you did rather than stopped. Pause is the explicit interruption you choose when you want the agent to stop while you work.\n\nIt is not a handoff. `needs_user_control` is the agent asking a person to do the next step on the same screen, and Resume (the console's Done) lets it continue; this is a person suspending a run that asked for nothing, so it works from `queued`, `running` and `needs_user_control` alike.\n\nTwo ways the hold ends badly, and they differ. RELEASE the run's lease while it is on hold and the run ends `failed` with reason `lease_lost`. Simply walk away, and when `manualControlUntil` passes the run is `canceled` with the explanation in `detail`. No new failure reason is used for either case.\n\nCalling it again on a run already on hold is safe: nothing is re-stamped and you get the same lease and the same window back.","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/runs/{runId}/pause","href":"/api/endpoints/runs/put-a-run-on-hold"},{"title":"Lift a stop and let the run carry on","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/runs/{runId}/resume","href":"/api/endpoints/runs/lift-a-stop-and-let-the-run-carry-on"},{"title":"Cancel a run","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/runs/{runId}/cancel","href":"/api/endpoints/runs/cancel-a-run"}]},{"group":"Discovery","pages":[{"title":"Discover where to authenticate","deprecated":null,"version":null,"openapi":"/api/openapi.json get /.well-known/oauth-protected-resource","href":"/api/endpoints/discovery/discover-where-to-authenticate"},{"title":"Discover where to authenticate, at the endpoint suffixed path","deprecated":null,"version":null,"openapi":"/api/openapi.json get /.well-known/oauth-protected-resource/mcp","href":"/api/endpoints/discovery/discover-where-to-authenticate-at-the-endpoint-suffixed-path"}]},{"group":"API keys","pages":[{"title":"List the org's keys","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/api-keys","href":"/api/endpoints/api-keys/list-the-orgs-keys"},{"title":"Mint an API key","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/api-keys","href":"/api/endpoints/api-keys/mint-an-api-key"},{"title":"Describe the calling key","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/api-keys/current","href":"/api/endpoints/api-keys/describe-the-calling-key"},{"title":"Revoke the calling key","deprecated":null,"version":null,"openapi":"/api/openapi.json delete /v1/api-keys/current","href":"/api/endpoints/api-keys/revoke-the-calling-key"},{"title":"Revoke a key","deprecated":null,"version":null,"openapi":"/api/openapi.json delete /v1/api-keys/{id}","href":"/api/endpoints/api-keys/revoke-a-key"},{"title":"Rename, renew or narrow a key","deprecated":null,"version":null,"openapi":"/api/openapi.json patch /v1/api-keys/{id}","href":"/api/endpoints/api-keys/rename-renew-or-narrow-a-key"},{"title":"Rotate a key","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/api-keys/{id}/rotate","href":"/api/endpoints/api-keys/rotate-a-key"},{"title":"Start a CLI sign-in","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/cli-sessions","href":"/api/endpoints/api-keys/start-a-cli-sign-in"},{"title":"Poll a CLI sign-in, and collect its key","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/cli-sessions/token","href":"/api/endpoints/api-keys/poll-a-cli-sign-in-and-collect-its-key"},{"title":"Look at a CLI sign-in before approving it","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/cli-sessions/{userCode}","href":"/api/endpoints/api-keys/look-at-a-cli-sign-in-before-approving-it"},{"title":"Approve a CLI sign-in","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/cli-sessions/{userCode}/approve","href":"/api/endpoints/api-keys/approve-a-cli-sign-in"},{"title":"Deny a CLI sign-in","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/cli-sessions/{userCode}/deny","href":"/api/endpoints/api-keys/deny-a-cli-sign-in"}]},{"group":"Usage","pages":[{"title":"List your org's receipts","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/receipts","href":"/api/endpoints/usage/list-your-orgs-receipts"},{"title":"Read one receipt","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/receipts/{idempotencyKey}","href":"/api/endpoints/usage/read-one-receipt"},{"title":"Mark a receipt reviewed","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/receipts/{idempotencyKey}/reviewed","href":"/api/endpoints/usage/mark-a-receipt-reviewed"},{"title":"List a phone's unclear actions","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/devices/{deviceId}/unclear-actions","href":"/api/endpoints/usage/list-a-phones-unclear-actions"},{"title":"Confirm a phone looks right","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/devices/{deviceId}/unclear-actions/confirm","href":"/api/endpoints/usage/confirm-a-phone-looks-right"},{"title":"Read your org's usage this period","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/usage","href":"/api/endpoints/usage/read-your-orgs-usage-this-period"}]},{"group":"Devices","pages":[{"title":"Small pictures of several devices' screens","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/device-thumbnails","href":"/api/endpoints/devices/small-pictures-of-several-devices-screens"},{"title":"List the devices you can see","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/devices","href":"/api/endpoints/devices/list-the-devices-you-can-see"},{"title":"Read one device","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/devices/{deviceId}","href":"/api/endpoints/devices/read-one-device"},{"title":"Rename a device","deprecated":null,"version":null,"openapi":"/api/openapi.json patch /v1/devices/{deviceId}","href":"/api/endpoints/devices/rename-a-device"},{"title":"Look at a device's screen","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/devices/{deviceId}/screenshot","href":"/api/endpoints/devices/look-at-a-devices-screen"},{"title":"Live video fault observation","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/devices/{deviceId}/image-maintenance/fault","href":"/api/endpoints/devices/live-video-fault-observation"},{"title":"Saved recovery plan cancellation","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/devices/{deviceId}/image-maintenance/cancel","href":"/api/endpoints/devices/saved-recovery-plan-cancellation"},{"title":"Original recovery result recheck","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/devices/{deviceId}/image-maintenance/recheck","href":"/api/endpoints/devices/original-recovery-result-recheck"},{"title":"Image recovery progress and availability","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/devices/{deviceId}/image-maintenance","href":"/api/endpoints/devices/image-recovery-progress-and-availability"},{"title":"Take a device","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/devices/{deviceId}/lease","href":"/api/endpoints/devices/take-a-device"},{"title":"Give a device back","deprecated":null,"version":null,"openapi":"/api/openapi.json delete /v1/devices/{deviceId}/lease","href":"/api/endpoints/devices/give-a-device-back"},{"title":"Keep a device longer","deprecated":null,"version":null,"openapi":"/api/openapi.json patch /v1/devices/{deviceId}/lease","href":"/api/endpoints/devices/keep-a-device-longer"},{"title":"Act on a device","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/devices/{deviceId}/actions","href":"/api/endpoints/devices/act-on-a-device"},{"title":"Who is driving a device","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/devices/{deviceId}/driving","href":"/api/endpoints/devices/who-is-driving-a-device"},{"title":"Open a live video session on a device","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/devices/{deviceId}/live-session","href":"/api/endpoints/devices/open-a-live-video-session-on-a-device"},{"title":"Wake a device's screen","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/devices/{deviceId}/wake","href":"/api/endpoints/devices/wake-a-devices-screen"},{"title":"Open a live view of a device","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/devices/{deviceId}/stream","href":"/api/endpoints/devices/open-a-live-view-of-a-device"},{"title":"Read the server's clock","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/time","href":"/api/endpoints/devices/read-the-servers-clock"},{"title":"List the devices your organisation currently holds","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/leases","href":"/api/endpoints/devices/list-the-devices-your-organisation-currently-holds"}]},{"group":"Copilot","pages":[{"title":"Ask the copilot","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/copilot","href":"/api/endpoints/copilot/ask-the-copilot"},{"title":"Answer a copilot approval","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/copilot/approvals","href":"/api/endpoints/copilot/answer-a-copilot-approval"},{"title":"Run one tool the person named","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/copilot/commands","href":"/api/endpoints/copilot/run-one-tool-the-person-named"},{"title":"Stop the turn this thread is running","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/copilot/threads/{id}/stop","href":"/api/endpoints/copilot/stop-the-turn-this-thread-is-running"},{"title":"Pick a cut copilot stream back up","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/copilot/threads/{id}/stream","href":"/api/endpoints/copilot/pick-a-cut-copilot-stream-back-up"},{"title":"Your copilot threads","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/copilot/threads","href":"/api/endpoints/copilot/your-copilot-threads"},{"title":"One thread, with a page of its messages","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/copilot/threads/{id}","href":"/api/endpoints/copilot/one-thread-with-a-page-of-its-messages"},{"title":"Delete a thread","deprecated":null,"version":null,"openapi":"/api/openapi.json delete /v1/copilot/threads/{id}","href":"/api/endpoints/copilot/delete-a-thread"},{"title":"Rename a thread","deprecated":null,"version":null,"openapi":"/api/openapi.json patch /v1/copilot/threads/{id}","href":"/api/endpoints/copilot/rename-a-thread"}]},{"group":"Webhooks","pages":[{"title":"Your webhook subscriptions","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/webhooks","href":"/api/endpoints/webhooks/your-webhook-subscriptions"},{"title":"Subscribe your system to what happens here","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/webhooks","href":"/api/endpoints/webhooks/subscribe-your-system-to-what-happens-here"},{"title":"Remove a subscription","deprecated":null,"version":null,"openapi":"/api/openapi.json delete /v1/webhooks/{webhookId}","href":"/api/endpoints/webhooks/remove-a-subscription"},{"title":"Enable or disable a subscription","deprecated":null,"version":null,"openapi":"/api/openapi.json patch /v1/webhooks/{webhookId}","href":"/api/endpoints/webhooks/enable-or-disable-a-subscription"},{"title":"Replace a signing secret","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/webhooks/{webhookId}/rotate","href":"/api/endpoints/webhooks/replace-a-signing-secret"},{"title":"Send a test delivery","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/webhooks/{webhookId}/test","href":"/api/endpoints/webhooks/send-a-test-delivery"},{"title":"What was delivered, and what happened","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/webhooks/{webhookId}/deliveries","href":"/api/endpoints/webhooks/what-was-delivered-and-what-happened"}]},{"group":"Robot purchases","pages":[{"title":"List your robot purchases","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/robot-purchases","href":"/api/endpoints/robot-purchases/list-your-robot-purchases"},{"title":"Read the monthly robot checkout offer","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/robot-purchases/offer","href":"/api/endpoints/robot-purchases/read-the-monthly-robot-checkout-offer"},{"title":"Open the original monthly robot checkout","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/robot-purchases/checkout","href":"/api/endpoints/robot-purchases/open-the-original-monthly-robot-checkout"},{"title":"Read your initial robot purchase receipt","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/robot-purchases/{orderId}","href":"/api/endpoints/robot-purchases/read-your-initial-robot-purchase-receipt"}]},{"group":"Managed Proxy","pages":[{"title":"Quote a multi-unit Proxy purchase","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/proxy-purchase-quotes","href":"/api/endpoints/managed-proxy/quote-a-multi-unit-proxy-purchase"},{"title":"Read the original purchase agreement","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/proxy-purchase-quotes/{quoteId}","href":"/api/endpoints/managed-proxy/read-the-original-purchase-agreement"},{"title":"Accept the original multi-unit purchase agreement","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/proxy-purchases","href":"/api/endpoints/managed-proxy/accept-the-original-multi-unit-purchase-agreement"},{"title":"Read unit delivery and original payment facts","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/proxy-purchases/{purchaseId}","href":"/api/endpoints/managed-proxy/read-unit-delivery-and-original-payment-facts"},{"title":"Cancel original undelivered units","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/proxy-purchases/{purchaseId}/cancel","href":"/api/endpoints/managed-proxy/cancel-original-undelivered-units"},{"title":"List managed Proxy products","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/proxy-products","href":"/api/endpoints/managed-proxy/list-managed-proxy-products"},{"title":"Read a managed Proxy product","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/proxy-products/{productId}","href":"/api/endpoints/managed-proxy/read-a-managed-proxy-product"},{"title":"Quote a managed Proxy purchase","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/proxy-quotes","href":"/api/endpoints/managed-proxy/quote-a-managed-proxy-purchase"},{"title":"Read the original quote","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/proxy-quotes/{quoteId}","href":"/api/endpoints/managed-proxy/read-the-original-quote"},{"title":"List your Proxy orders","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/proxy-orders","href":"/api/endpoints/managed-proxy/list-your-proxy-orders"},{"title":"Reserve a quoted Proxy order","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/proxy-orders","href":"/api/endpoints/managed-proxy/reserve-a-quoted-proxy-order"},{"title":"Read a Proxy order and its settlement","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/proxy-orders/{orderId}","href":"/api/endpoints/managed-proxy/read-a-proxy-order-and-its-settlement"},{"title":"Request hosted Checkout for an order","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/proxy-orders/{orderId}/checkout","href":"/api/endpoints/managed-proxy/request-hosted-checkout-for-an-order"},{"title":"Cancel a Proxy order","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/proxy-orders/{orderId}/cancel","href":"/api/endpoints/managed-proxy/cancel-a-proxy-order"},{"title":"List your managed Proxies","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/proxies","href":"/api/endpoints/managed-proxy/list-your-managed-proxies"},{"title":"Read a managed Proxy","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/proxies/{proxyId}","href":"/api/endpoints/managed-proxy/read-a-managed-proxy"},{"title":"Rename a managed Proxy","deprecated":null,"version":null,"openapi":"/api/openapi.json patch /v1/proxies/{proxyId}","href":"/api/endpoints/managed-proxy/rename-a-managed-proxy"},{"title":"Archive an expired detached Proxy","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/proxies/{proxyId}/archive","href":"/api/endpoints/managed-proxy/archive-an-expired-detached-proxy"},{"title":"List your Proxy network operations","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/proxy-operations","href":"/api/endpoints/managed-proxy/list-your-proxy-network-operations"},{"title":"Connect or disconnect a Proxy","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/proxy-operations","href":"/api/endpoints/managed-proxy/connect-or-disconnect-a-proxy"},{"title":"Read a Proxy operation","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/proxy-operations/{operationId}","href":"/api/endpoints/managed-proxy/read-a-proxy-operation"},{"title":"Read a device's confirmed Proxy relationship","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/devices/{deviceId}/proxy","href":"/api/endpoints/managed-proxy/read-a-devices-confirmed-proxy-relationship"}]},{"group":"Minute billing","pages":[{"title":"/v1/minute/requests/:requestId","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/minute/requests/{requestId}","href":"/api/endpoints/minute-billing/v1minuterequests:requestid"},{"title":"/v1/minute/catalog","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/minute/catalog","href":"/api/endpoints/minute-billing/v1minutecatalog"},{"title":"/v1/minute/wallet","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/minute/wallet","href":"/api/endpoints/minute-billing/v1minutewallet"},{"title":"/v1/minute/topup-quotes","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/minute/topup-quotes","href":"/api/endpoints/minute-billing/v1minutetopup-quotes"},{"title":"/v1/minute/topups","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/minute/topups","href":"/api/endpoints/minute-billing/v1minutetopups"},{"title":"/v1/minute/topups/:id","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/minute/topups/{id}","href":"/api/endpoints/minute-billing/v1minutetopups:id"},{"title":"/v1/minute/topups/:id/abandon","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/minute/topups/{id}/abandon","href":"/api/endpoints/minute-billing/v1minutetopups:idabandon"},{"title":"/v1/minute/starts","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/minute/starts","href":"/api/endpoints/minute-billing/v1minutestarts"},{"title":"/v1/minute/starts/:id","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/minute/starts/{id}","href":"/api/endpoints/minute-billing/v1minutestarts:id"},{"title":"/v1/minute/orders","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/minute/orders","href":"/api/endpoints/minute-billing/v1minuteorders"},{"title":"/v1/minute/orders","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/minute/orders","href":"/api/endpoints/minute-billing/v1minuteorders-1"},{"title":"/v1/minute/orders/:id","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/minute/orders/{id}","href":"/api/endpoints/minute-billing/v1minuteorders:id"},{"title":"/v1/minute/orders/:id/cancel","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/minute/orders/{id}/cancel","href":"/api/endpoints/minute-billing/v1minuteorders:idcancel"},{"title":"/v1/minute/rentals/:deviceId","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/minute/rentals/{deviceId}","href":"/api/endpoints/minute-billing/v1minuterentals:deviceid"},{"title":"/v1/minute/rentals/:deviceId/return","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/minute/rentals/{deviceId}/return","href":"/api/endpoints/minute-billing/v1minuterentals:deviceidreturn"},{"title":"/v1/minute/rentals/:deviceId/resume","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/minute/rentals/{deviceId}/resume","href":"/api/endpoints/minute-billing/v1minuterentals:deviceidresume"},{"title":"/v1/minute/refunds","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/minute/refunds","href":"/api/endpoints/minute-billing/v1minuterefunds"},{"title":"/v1/minute/refunds","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/minute/refunds","href":"/api/endpoints/minute-billing/v1minuterefunds-1"},{"title":"/v1/minute/cases","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/minute/cases","href":"/api/endpoints/minute-billing/v1minutecases"},{"title":"/v1/minute/cases","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/minute/cases","href":"/api/endpoints/minute-billing/v1minutecases-1"},{"title":"/v1/minute/cases/:id","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/minute/cases/{id}","href":"/api/endpoints/minute-billing/v1minutecases:id"},{"title":"/v1/minute/refunds/:id","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/minute/refunds/{id}","href":"/api/endpoints/minute-billing/v1minuterefunds:id"}]},{"group":"Provisioning","pages":[{"title":"Check whether your organisation is provisioned","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/admission","href":"/api/endpoints/provisioning/check-whether-your-organisation-is-provisioned"},{"title":"What your organisation has bought, and where each purchase got to","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/fulfilments","href":"/api/endpoints/provisioning/what-your-organisation-has-bought-and-where-each-purchase-got-to"},{"title":"Whether one checkout was paid","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/orders/{orderId}/payment-status","href":"/api/endpoints/provisioning/whether-one-checkout-was-paid"},{"title":"Cancelling online is retired: contact support","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/fulfilments/{id}/cancel","href":"/api/endpoints/provisioning/cancelling-online-is-retired:-contact-support"},{"title":"Returning online is retired: contact support","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/fulfilments/{id}/return","href":"/api/endpoints/provisioning/returning-online-is-retired:-contact-support"},{"title":"Stop future Cloud phone renewal at Stripe's current period end","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/fulfilments/{id}/cancel-renewal","href":"/api/endpoints/provisioning/stop-future-cloud-phone-renewal-at-stripes-current-period-end"},{"title":"Read a Cloud phone's current monthly renewal state","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/fulfilments/{id}/renewal-status","href":"/api/endpoints/provisioning/read-a-cloud-phones-current-monthly-renewal-state"},{"title":"What you owe next","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/billing/upcoming","href":"/api/endpoints/provisioning/what-you-owe-next"},{"title":"Open the billing portal","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/billing/portal-sessions","href":"/api/endpoints/provisioning/open-the-billing-portal"},{"title":"List what can be bought and what it costs","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/skus","href":"/api/endpoints/provisioning/list-what-can-be-bought-and-what-it-costs"},{"title":"Start provisioning this organisation","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/checkout-sessions","href":"/api/endpoints/provisioning/start-provisioning-this-organisation"},{"title":"Check one returned Checkout now","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/checkout-sessions/{orderId}/confirm","href":"/api/endpoints/provisioning/check-one-returned-checkout-now"},{"title":"Where the payment provider delivers","deprecated":null,"version":null,"openapi":"/api/openapi.json post /webhooks/stripe","href":"/api/endpoints/provisioning/where-the-payment-provider-delivers"},{"title":"Where the identity provider delivers","deprecated":null,"version":null,"openapi":"/api/openapi.json post /webhooks/clerk","href":"/api/endpoints/provisioning/where-the-identity-provider-delivers"}]},{"group":"Notifications","pages":[{"title":"The bell, and the list behind it","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/notifications","href":"/api/endpoints/notifications/the-bell-and-the-list-behind-it"},{"title":"Mark notifications read","deprecated":null,"version":null,"openapi":"/api/openapi.json post /v1/notifications/read","href":"/api/endpoints/notifications/mark-notifications-read"},{"title":"Which emails you receive","deprecated":null,"version":null,"openapi":"/api/openapi.json get /v1/me/notification-preferences","href":"/api/endpoints/notifications/which-emails-you-receive"},{"title":"Change which emails you receive","deprecated":null,"version":null,"openapi":"/api/openapi.json patch /v1/me/notification-preferences","href":"/api/endpoints/notifications/change-which-emails-you-receive"}]}]}]},{"tab":"Help","pages":[{"title":"Help","href":"/help/overview"}]}]},"basePath":"","title":"Read a run, optionally waiting for it to move - PhoneUse","deploymentId":"dpl_2pTxFtyBudBMYZiCw1MyvoA1wxpd","buildId":"dpl_2pTxFtyBudBMYZiCw1MyvoA1wxpd","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-BtG4DSkw.js","snippetPresets-C1k1xDhp.js","utils-PMJoEt4Y.js","style-to-object-BY3JEAdk.js","utils-DW3Pr7Jq.js","v4-DIgz8zy6.js","addUniqueKeysToSchema-DIISLO2w.js","conditional-requirements-CFM0id0Q.js","cloneDeep-BErNCZCm.js","_Uint8Array-f0PCu9f_.js","isObject-FP1Yky1u.js","ApiExamples-OjY-8mqu.js","usePlaygroundInputsStore-B2HS2hUb.js","shallow-DVFuuIDQ.js","isEqual-DG0UKiQC.js","CodeSnippets-Cy6FBgwN.js","CodeSnippet-D1PtG8ed.js","getApiPlaygroundDisplay-Dkx2eNtL.js","Page-C8Cg25if.js","DynamicMarkdown-BvJIe00T.js","SectionHeading-B0rKYV8d.js","icon-yclzBff4.js","MethodPill-DxA11cCF.js","getPastedJson-CpkIDpMk.js","DuplicateIcon-CFCQNJ-D.js","axios-CsQoIw0U.js","Markdown-CK5C-fmV.js","AssistantPageLink-Cw134Dd-.js","dist-3xM3Qrc7.js","lib-DMeTj1gb.js","lib-B8HbPgcC.js","katex-Dbtb6Wk7.js","html-void-elements-mCSPHezU.js","marked.esm-CZWythHk.js"]}