What the control plane hands back, and how to confirm an action later.
An agent driving a real device has to answer one question after every call:
did that actually happen? PhoneUse answers it with a recorded outcome rather
than with an acknowledgement, and gives you a way to look the answer up again
after the fact.Three things carry that guarantee: the typed result, the idempotency key, and
the observed frame.
The typed result
Every successful call returns typed structuredContent, shaped by the output
schema that tool publishes. The same value is also written into a text block
for older consumers, so a client that reads either one sees the same data.For an action, that value is an outcome:
status: "committed" means the device applied the action. It is not an
acknowledgement that the request arrived.
committedAt is when the backend confirmed the commit, on the control
plane’s clock.
deduplicated: true means this response was replayed from the ledger and
the gesture did not happen again.
Failures never appear in this shape. A failed action is an error result, and
errors have their own envelope.
The idempotency key
idempotencyKey is a short printable ASCII request id that you generate and
pass with an action. Its exact length and character bounds are published in
the tool reference. It is optional, and it is worth passing
every time.With a key of your own, a retry of a request whose response you lost replays
what was recorded instead of pressing the glass a second time. Without one the
control plane generates a key so the action is still recorded, but it cannot
recognise your retry as a retry, because it never saw your first attempt’s
key.Two limits are worth knowing before you build a retry loop:
A key that failed terminally will not replay into a fresh attempt. Reusing
it replays the recorded failure, and the error tells you to retry under a new
key. Idempotency protects you from double execution; it is not a way to make
a failed action run again.
Some outcomes are genuinely unknown. The error set includes a case for an
action whose result the control plane could not establish. Treat it as
neither done nor not done, and resolve it by reading the receipt rather than
by retrying blind.
Keys beginning with agent: are refused. That prefix belongs to the control
plane’s own runs, and a caller able to write there could pre create receipts
for a run’s future actions and have every one of them replay instead of
execute.
Reuse a key only for the same intended action. A different tap under the
same key is a conflict, not a retry.
Looking an outcome up later
When a response is lost, do not retry blind. Ask what happened:
found: false is a normal answer, not an error. It means no receipt exists
under that key, so the action never began, and the same key is safe to
retry.Two fields deserve attention when a receipt is not simply committed:
reason: "interrupted_by_restart" means the control plane restarted while
the action was in flight, so the request was closed as failed rather than
guessed either way.
reason: "outcome_unknown" means the transport to the device was lost after
dispatch. Whether the device acted is genuinely unknown.
Both arrive with requiresManualReview: true. That flag exists because
guessing is worse than admitting the gap: a person has to reconcile what the
device actually did.get_receipt reads receipts, so it is available to a read only credential. A
lease id and fencing token are never projected into it, because they are
bearer credentials rather than audit fields.
The observed frame
observedFrame is the other half of the trace, and it works forwards rather
than backwards.A screenshot issues a frameId. Pass that id back on the next action and the
action is refused unless the frame is still the device’s latest. A refusal comes
back as stale_frame, telling you the screen moved between deciding and acting.
There is no clock on it: a frame does not age out, so however long you spend
deciding does not matter.This is what answers the classic worry of a vision driven loop: deciding on a
picture and then tapping a screen somebody else has changed. It answers it by
telling you: every action comes back with others, which says
how many actions another principal took since the frame you named, when, and
whether by a person or an agent. An agent that names a frame is also refused
when that count is above zero, by default; pass refuseIfOthersActed: false to
be told without being stopped.Naming a frame that was never issued is still an error, and so is naming one so
far back that the control plane no longer holds it.Not every device supports it. A device whose capabilities report
framesAreReferenceable: false has no visual observation to bind to, and
passing observedFrame there is refused as capability_unsupported.
How to consume an error
Errors arrive with isError: true and come in exactly two shapes, so there is
no ambiguity about how to parse one.
A device or control plane error. The text block is a JSON envelope with
a stable code, a message, and retryable, plus any fields specific to
that error. Branch on code.
A schema rejection. The text block is prose, and it will not parse as
JSON. Your parameters were wrong. Fix them before resending.
So: try to parse the text block. If it parses, branch on the code. If it does
not, you have an argument problem.Errors never carry structuredContent. That is deliberate, because a standard
MCP client validates any structuredContent it sees against the tool’s output
schema with no exemption for errors, and an envelope there would break it.The full list of codes is in the error reference, and the
common ones are explained in Troubleshooting.
Why usage and evidence agree
The receipt ledger is the system of record. Usage is derived from it rather
than counted separately, so what you are billed for and what you can look up
with get_receipt are the same events. See Metering units.
{"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.4227","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":[],"googleFontsInlined":false},"customCss":[]}
{"page":{"pagePath":"getting-started/trace","slug":"/getting-started/trace","pageMetadata":{"title":"Reading a trace","description":"What the control plane hands back, and how to confirm an action later.","href":"/getting-started/trace"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"What the control plane hands back, and how to confirm an action later.\"\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,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,ol:`ol`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`An agent driving a real device has to answer one question after every call:\ndid that actually happen? PhoneUse answers it with a recorded outcome rather\nthan with an acknowledgement, and gives you a way to look the answer up again\nafter the fact.`}),`\n`,_jsx(_components.p,{children:`Three things carry that guarantee: the typed result, the idempotency key, and\nthe observed frame.`}),`\n`,_jsx(Heading,{level:`2`,id:`the-typed-result`,children:`The typed result`}),`\n`,_jsxs(_components.p,{children:[`Every successful call returns typed `,_jsx(_components.code,{children:`structuredContent`}),`, shaped by the output\nschema that tool publishes. The same value is also written into a text block\nfor older consumers, so a client that reads either one sees the same data.`]}),`\n`,_jsx(_components.p,{children:`For an action, that value is an outcome:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`6`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`6`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"status\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"committed\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"committedAt\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"2026-08-29T10:14:08.377Z\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"idempotencyKey\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"signin-button-1\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"deduplicated\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`false`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`Read it precisely.`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`status: \"committed\"`}),` means the `,_jsx(_components.strong,{children:`device`}),` applied the action. It is not an\nacknowledgement that the request arrived.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`committedAt`}),` is when the backend confirmed the commit, on the control\nplane’s clock.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`deduplicated: true`}),` means this response was replayed from the ledger and\nthe gesture did not happen again.`]}),`\n`]}),`\n`,_jsx(_components.p,{children:`Failures never appear in this shape. A failed action is an error result, and\nerrors have their own envelope.`}),`\n`,_jsx(Heading,{level:`2`,id:`the-idempotency-key`,children:`The idempotency key`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`idempotencyKey`}),` is a short printable ASCII request id that you generate and\npass with an action. Its exact length and character bounds are published in\nthe `,_jsx(_components.a,{href:`/mcp/reference`,children:`tool reference`}),`. It is optional, and it is worth passing\nevery time.`]}),`\n`,_jsxs(_components.p,{children:[`With a key of your own, a retry of a request whose response you lost replays\nwhat was recorded instead of pressing the glass a second time. Without one the\ncontrol plane generates a key so the action is still recorded, but it cannot\nrecognise `,_jsx(_components.strong,{children:`your`}),` retry as a retry, because it never saw your first attempt’s\nkey.`]}),`\n`,_jsx(_components.p,{children:`Two limits are worth knowing before you build a retry loop:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`A key that failed terminally will not replay into a fresh attempt.`}),` Reusing\nit replays the recorded failure, and the error tells you to retry under a new\nkey. Idempotency protects you from double execution; it is not a way to make\na failed action run again.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Some outcomes are genuinely unknown.`}),` The error set includes a case for an\naction whose result the control plane could not establish. Treat it as\nneither done nor not done, and resolve it by reading the receipt rather than\nby retrying blind.`]}),`\n`]}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[`Keys beginning with `,_jsx(_components.code,{children:`agent:`}),` are refused. That prefix belongs to the control\nplane’s own runs, and a caller able to write there could pre create receipts\nfor a run’s future actions and have every one of them replay instead of\nexecute.`]})}),`\n`,_jsxs(_components.p,{children:[`Reuse a key only for the `,_jsx(_components.strong,{children:`same intended action`}),`. A different tap under the\nsame key is a conflict, not a retry.`]}),`\n`,_jsx(Heading,{level:`2`,id:`looking-an-outcome-up-later`,children:`Looking an outcome up later`}),`\n`,_jsx(_components.p,{children:`When a response is lost, do not retry blind. Ask what happened:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`4`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`4`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"name\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"get_receipt\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"arguments\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: { `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"deviceId\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"cloud-phone-01\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"idempotencyKey\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"signin-button-1\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`15`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`15`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"found\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`true`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"receipt\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"orgId\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"org_local\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"deviceId\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"cloud-phone-01\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"idempotencyKey\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"signin-button-1\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"backendKind\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"adb_cloud\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"action\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"tap\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"argsSummary\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: { `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"x\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`500`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"y\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`820`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` },`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"observedFrame\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"frm_5b81...\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"status\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"committed\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"requestedAt\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"2026-08-29T10:14:07.905Z\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"committedAt\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"2026-08-29T10:14:08.377Z\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`found: false`}),` is a normal answer, not an error. It means no receipt exists\nunder that key, so the action never began, and the `,_jsx(_components.strong,{children:`same`}),` key is safe to\nretry.`]}),`\n`,_jsx(_components.p,{children:`Two fields deserve attention when a receipt is not simply committed:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`reason: \"interrupted_by_restart\"`}),` means the control plane restarted while\nthe action was in flight, so the request was closed as failed rather than\nguessed either way.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`reason: \"outcome_unknown\"`}),` means the transport to the device was lost after\ndispatch. Whether the device acted is genuinely unknown.`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`Both arrive with `,_jsx(_components.code,{children:`requiresManualReview: true`}),`. That flag exists because\nguessing is worse than admitting the gap: a person has to reconcile what the\ndevice actually did.`]}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`get_receipt`}),` reads receipts, so it is available to a read only credential. A\nlease id and fencing token are never projected into it, because they are\nbearer credentials rather than audit fields.`]}),`\n`,_jsx(Heading,{level:`2`,id:`the-observed-frame`,children:`The observed frame`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`observedFrame`}),` is the other half of the trace, and it works forwards rather\nthan backwards.`]}),`\n`,_jsxs(_components.p,{children:[`A screenshot issues a `,_jsx(_components.code,{children:`frameId`}),`. Pass that id back on the next action and the\naction is refused unless the frame is still the device’s latest. A refusal comes\nback as `,_jsx(_components.code,{children:`stale_frame`}),`, telling you the screen moved between deciding and acting.\nThere is no clock on it: a frame does not age out, so however long you spend\ndeciding does not matter.`]}),`\n`,_jsxs(_components.p,{children:[`This is what answers the classic worry of a vision driven loop: deciding on a\npicture and then tapping a screen somebody else has changed. It answers it by\ntelling you: every action comes back with `,_jsx(_components.code,{children:`others`}),`, which says\nhow many actions another principal took since the frame you named, when, and\nwhether by a person or an agent. An agent that names a frame is also refused\nwhen that count is above zero, by default; pass `,_jsx(_components.code,{children:`refuseIfOthersActed: false`}),` to\nbe told without being stopped.`]}),`\n`,_jsx(_components.p,{children:`Naming a frame that was never issued is still an error, and so is naming one so\nfar back that the control plane no longer holds it.`}),`\n`,_jsxs(_components.p,{children:[`Not every device supports it. A device whose capabilities report\n`,_jsx(_components.code,{children:`framesAreReferenceable: false`}),` has no visual observation to bind to, and\npassing `,_jsx(_components.code,{children:`observedFrame`}),` there is refused as `,_jsx(_components.code,{children:`capability_unsupported`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`how-to-consume-an-error`,children:`How to consume an error`}),`\n`,_jsxs(_components.p,{children:[`Errors arrive with `,_jsx(_components.code,{children:`isError: true`}),` and come in exactly two shapes, so there is\nno ambiguity about how to parse one.`]}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`A device or control plane error.`}),` The text block is a JSON envelope with\na stable `,_jsx(_components.code,{children:`code`}),`, a `,_jsx(_components.code,{children:`message`}),`, and `,_jsx(_components.code,{children:`retryable`}),`, plus any fields specific to\nthat error. Branch on `,_jsx(_components.code,{children:`code`}),`.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`A schema rejection.`}),` The text block is prose, and it will not parse as\nJSON. Your parameters were wrong. Fix them before resending.`]}),`\n`]}),`\n`,_jsx(_components.p,{children:`So: try to parse the text block. If it parses, branch on the code. If it does\nnot, you have an argument problem.`}),`\n`,_jsxs(_components.p,{children:[`Errors never carry `,_jsx(_components.code,{children:`structuredContent`}),`. That is deliberate, because a standard\nMCP client validates any `,_jsx(_components.code,{children:`structuredContent`}),` it sees against the tool’s output\nschema with no exemption for errors, and an envelope there would break it.`]}),`\n`,_jsxs(_components.p,{children:[`The full list of codes is in the `,_jsx(_components.a,{href:`/mcp/errors`,children:`error reference`}),`, and the\ncommon ones are explained in `,_jsx(_components.a,{href:`/help/troubleshooting`,children:`Troubleshooting`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`why-usage-and-evidence-agree`,children:`Why usage and evidence agree`}),`\n`,_jsxs(_components.p,{children:[`The receipt ledger is the system of record. Usage is derived from it rather\nthan counted separately, so what you are billed for and what you can look up\nwith `,_jsx(_components.code,{children:`get_receipt`}),` are the same events. See `,_jsx(_components.a,{href:`/billing/units`,children:`Metering units`}),`.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Reading a trace","description":"What the control plane hands back, and how to confirm an action later.","href":"/getting-started/trace"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"The typed result","slug":"the-typed-result","depth":2,"children":[]},{"title":"The idempotency key","slug":"the-idempotency-key","depth":2,"children":[]},{"title":"Looking an outcome up later","slug":"looking-an-outcome-up-later","depth":2,"children":[]},{"title":"The observed frame","slug":"the-observed-frame","depth":2,"children":[]},{"title":"How to consume an error","slug":"how-to-consume-an-error","depth":2,"children":[]},{"title":"Why usage and evidence agree","slug":"why-usage-and-evidence-agree","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"phonebase","siteName":"PhoneUse","title":"Reading a trace - PhoneUse","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-21T16:42:03.560Z","originalFileLocation":"getting-started/trace.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=\"What the control plane hands back, and how to confirm an action later.\">\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=\"Reading a trace - PhoneUse\">\u003cmeta data-mint-head property=\"og:description\" content=\"What the control plane hands back, and how to confirm an action later.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"PhoneUse\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.phoneuse.com/getting-started/trace\">\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=Getting+started\u0026amp;title=Reading+a+trace\u0026amp;description=What+the+control+plane+hands+back%2C+and+how+to+confirm+an+action+later.\u0026amp;theme=370fb2999dfbb8f85a217f41\u0026amp;signature=c288eb75b96f59716da6a825e9357218d613292197219e0ed28994342b14045b\">\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=\"Reading a trace - PhoneUse\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"What the control plane hands back, and how to confirm an action later.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://phonebase.mintlify.site/_mintlify/api/og/v2?division=Getting+started\u0026amp;title=Reading+a+trace\u0026amp;description=What+the+control+plane+hands+back%2C+and+how+to+confirm+an+action+later.\u0026amp;theme=370fb2999dfbb8f85a217f41\u0026amp;signature=c288eb75b96f59716da6a825e9357218d613292197219e0ed28994342b14045b\">\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/getting-started/trace\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/getting-started/trace.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/getting-started/trace#webpage\",\"url\":\"https://docs.phoneuse.com/getting-started/trace\",\"name\":\"Reading a trace\",\"description\":\"What the control plane hands back, and how to confirm an action later.\",\"dateModified\":\"2026-10-21T16:42:03.560Z\",\"isPartOf\":{\"@id\":\"https://docs.phoneuse.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.phoneuse.com/getting-started/trace#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.phoneuse.com/getting-started/trace#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Getting started\",\"item\":\"https://docs.phoneuse.com\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Reading a trace\",\"item\":\"https://docs.phoneuse.com/getting-started/trace\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.phoneuse.com/getting-started/trace#article\",\"headline\":\"Reading a trace\",\"name\":\"Reading a trace\",\"description\":\"What the control plane hands back, and how to confirm an action later.\",\"url\":\"https://docs.phoneuse.com/getting-started/trace\",\"mainEntityOfPage\":{\"@id\":\"https://docs.phoneuse.com/getting-started/trace#webpage\"},\"dateModified\":\"2026-10-21T16:42:03.560Z\",\"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":"/getting-started/trace.md","siteName":"PhoneUse","nav":{"global":null,"tabs":[{"tab":"Docs","groups":[{"group":"Getting started","pages":[{"title":"PhoneUse docs","href":""},{"title":"Quickstart","href":"/quickstart"},{"title":"The console","href":"/getting-started/console"},{"title":"MCP config","href":"/getting-started/mcp-config"},{"title":"First session","description":"Acquire a device, observe it, act on it, release it, one call at a time.","href":"/getting-started/first-session"},{"title":"Reading a trace","href":"/getting-started/trace"},{"title":"For agents","description":"Machine readable entry points, and which MCP server is which.","href":"/getting-started/for-agents"}]},{"group":"Guides","pages":[{"title":"Buy and drive a device","href":"/guides/first-device"},{"title":"Webhooks","href":"/guides/webhooks"},{"title":"Install apps from the App Store","href":"/guides/upload-app-package"}]},{"group":"MCP","pages":[{"title":"MCP surface","href":"/mcp/overview"},{"title":"Tool reference","href":"/mcp/reference"},{"title":"Errors","href":"/mcp/errors"},{"title":"Transports","href":"/mcp/transports"},{"title":"Authentication","href":"/mcp/auth"},{"title":"Progress and takeover","href":"/mcp/progress-and-takeover"}]},{"group":"Copilot","pages":[{"title":"Chat with the copilot","href":"/copilot/chat"}]},{"group":"Device capabilities","pages":[{"title":"Device tiers","href":"/devices/tiers"},{"title":"Capabilities","href":"/devices/capabilities"}]},{"group":"Agent tier","pages":[{"title":"Agent tier","href":"/agent/overview"},{"title":"Bring your own worker","href":"/agent/worker"},{"title":"Runs","href":"/agent/runs"}]},{"group":"CLI","pages":[{"title":"CLI","href":"/cli/overview"},{"title":"Installation","href":"/cli/installation"},{"title":"Commands","href":"/cli/commands"},{"title":"CLI in CI","href":"/cli/ci-cd"}]},{"group":"Security and tenancy","pages":[{"title":"Org isolation","href":"/security/org-isolation"},{"title":"Frame retention","href":"/security/frame-retention"},{"title":"A leaked credential","href":"/security/leaked-credentials"},{"title":"Acceptable use","href":"/security/acceptable-use"}]},{"group":"Billing and metering","pages":[{"title":"Metering units","href":"/billing/units"},{"title":"Billing modes","href":"/billing/modes"},{"title":"Spending controls","href":"/billing/spending-controls"}]},{"group":"Changelog","pages":[{"title":"Changelog","href":"/changelog"}]}]},{"tab":"API","pages":[{"title":"API","href":"/api"}]},{"tab":"Help","pages":[{"title":"Help","href":"/help/overview"}]}]},"basePath":"","title":"Reading a trace - PhoneUse","deploymentId":"dpl_vSEmv961Ncyvz1psVwgUnTXQMSYk","buildId":"dpl_vSEmv961Ncyvz1psVwgUnTXQMSYk","dynamics":[],"chunks":[]}