Agent SDK reference - TypeScript changedagent-sdk/typescript
Nearest release: v2.1.261, published 9 hours before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+10added
Lines−2removed
From line
1,262
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits114to this page, all time
The whole hunk
from line 1262, old and new numbered
/
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 1262
12621262 ttft_stream_ms?: number;
12631263 user_message_uuid?: string;
12641264 request_sent_wall_ms?: number;
1265 first_content_frame_ms?: number;
1266 first_stream_post_ms?: number;
1267 first_stream_post_ack_ms?: number;
1268 first_stream_post_wall_ms?: number;
12651269 total_cost_usd: number;
12661270 usage: NonNullableUsage;
12671271 modelUsage: { [modelName: string]: ModelUsage };
from line 1313
13091313* `ttft_stream_ms`: time in milliseconds until the first `message_start` stream event, when the response stream opens. Lower than `ttft_ms`; the gap between the two is time spent streaming the first message. Present on the success arm only.
13101314* `user_message_uuid`: the `uuid` of the message you sent that started this turn. See [`user_message_uuid`](#user_message_uuid) for which results carry it.
13111315* `request_sent_wall_ms`: epoch milliseconds at which Claude Code dispatched the API request, for joins against server-side timestamps. Present on the success arm only, together with `user_message_uuid`, when `is_error` is false.
1316* `first_content_frame_ms`: time in milliseconds until the first `content_block_start` or `content_block_delta` stream event, counting thinking blocks as content. Present on the success arm only, when `is_error` is false. Requires Agent SDK v0.3.260 or later.
1317* `first_stream_post_ms`, `first_stream_post_ack_ms`, `first_stream_post_wall_ms`: timings for uploading the turn's first stream event. Claude Code records them only in sessions it streams to claude.ai, such as [cloud sessions](/docs/en/claude-code-on-the-web), and the results `query()` yields don't carry them. Requires Agent SDK v0.3.260 or later.
13121318* `usage`: main agent loop only. Excludes subagent and auxiliary model calls, and is per-turn in streaming-input sessions. Prefer `modelUsage` for token/cost accounting.
13131319* `modelUsage`: per-model totals for every model call made through the query pipeline during this `query()` call, including the main loop, subagents, and internal calls such as compaction and Workflow agents. Helper calls outside that pipeline, such as the permission classifier and token-counting requests, are excluded. In streaming-input sessions the totals are cumulative across turns, so read the latest result rather than summing across results. See [Track costs in streaming input mode](/docs/en/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode) for resets and [Recover totals after a session crash](/docs/en/agent-sdk/cost-tracking#recover-totals-after-a-session-crash) for zeroed results.
13141320* `total_cost_usd`: cumulative estimated cost in USD for this `query()` call, covering the same calls as `modelUsage` and reset at the same points. It is an estimate, not a billing statement. See [Track cost and usage](/docs/en/agent-sdk/cost-tracking) for accuracy caveats.
from line 1348
13421348
13431349#### `user_message_uuid`
13441350
1345The `uuid` of the [`SDKUserMessage`](#sdkusermessage) that started the turn, echoed so you can match Claude Code's reply to the message you sent. Claude Code echoes it only if you set `uuid` on that message. The field is optional on `SDKUserMessage`, and a string prompt passed to `query()` carries none. When you set it, Claude Code echoes it on two kinds of frame:
1351The `uuid` of the [`SDKUserMessage`](#sdkusermessage) that started the turn, echoed so you can match Claude Code's reply to the message you sent. Claude Code echoes it only if you set `uuid` on that message. The field is optional on `SDKUserMessage`, and a string prompt passed to `query()` carries none. When you set it, Claude Code echoes it on these frames:
13461352
13471353* **The result**: on the success arm with `is_error` false, together with `request_sent_wall_ms`, which requires Agent SDK v0.3.216 or later. On an error result that answers a message you sent, Claude Code echoes the field alone, which requires Agent SDK v0.3.246 or later.
1348* **The turn's first reply**: the first [assistant message](#sdkassistantmessage), or with `includePartialMessages` the first [stream event](#sdkpartialassistantmessage) whose `event.type` isn't `ping`, so you can bind the reply before the result arrives. When a turn streams nothing, Claude Code sets it on the first assistant message instead. One frame per turn carries it. Requires Agent SDK v0.3.246 or later.
1354* **The turn's first reply**: the first [assistant message](#sdkassistantmessage), or with `includePartialMessages` the first [stream event](#sdkpartialassistantmessage) whose `event.type` isn't `ping`, so you can bind the reply before the result arrives. When a turn streams nothing, Claude Code sets it on the first assistant message instead. One reply frame per turn carries it. Requires Agent SDK v0.3.246 or later.
1355* **Every [`thinking_tokens`](#sdkthinkingtokensmessage) frame of the turn**: so you can attribute thinking progress to the message you sent without waiting for the turn's first reply. Requires Agent SDK v0.3.260 or later.
13491356
13501357Claude Code omits the field in these cases:
13511358
from line 3620
36133620 codeText: string;
36143621 result: string;
36153622 durationMs: number;
3616 url: string;
3617 artifactRead?: {
3618 slug: string;
3619 ver?: string;
3620 seeded?: false;
3621 };
3622};
3623```
3624
3625Returns the fetched content with HTTP status and metadata.
3626
3627`artifactRead` is present only when Claude fetched an artifact the session can publish to, and it always carries that artifact's `slug`.
3628
3629`seeded` is `false` on a read that didn't deliver the page's full source, and that entry carries no `ver`. The field requires Agent SDK v0.3.239 or later.
3630
3631### WebSearch
3632
3633**Tool name:** `WebSearch`
3634
3635```typescript theme={null}
3636type WebSearchOutput = {
3637 query: string;
3638 results: Array<
3639 | {
3640 tool_use_id: string;
3641 content: Array<{ title: string; url: string }>;
3642 }
3643 | string
3644 >;
3645 durationSeconds: number;
3646 searchCount?: number;
3647};
3648```
3649
3650Returns search results from the web.
3651
3652### Workflow
3653
3654**Tool name:** `Workflow`
3655
3656```typescript theme={null}
3657type WorkflowOutput = {
3658 status: "async_launched" | "remote_launched";
3659 taskId: string;
3660 taskType?: "local_workflow" | "remote_agen
3623 url: strin
No line in this hunk matches that.