661 661
662### `SDKControlGetContextUsageResponse`662### `SDKControlGetContextUsageResponse`
663 663
664Return type of [`getContextUsage()`](#query-object). This is the same payload the `/context` command renders in an interactive session, so alongside the token counts it carries display fields such as `color`, `gridRows`, and `percentage` that `/context` uses to draw its usage grid.664Return type of [`getContextUsage()`](#query-object). This is the same payload Claude Code renders for the `/context` command in an interactive session, so alongside the token counts it carries display fields such as `color` and `gridRows` that Claude Code uses to draw the `/context` usage grid.
665
666When you send `/context` as a prompt instead of calling the method, Claude Code attaches an [`SDKContextUsage`](#sdkcontextusage) payload to the `context_usage` field of the assistant message that delivers the result. That field requires Agent SDK v0.3.232 or later.
665 667
666```typescript theme={null}668```typescript theme={null}
667type SDKControlGetContextUsageResponse = {669type SDKControlGetContextUsageResponse = {
764* `memoryFiles` lists each loaded memory file with its cost.766* `memoryFiles` lists each loaded memory file with its cost.
765* `skills.skillFrontmatter` attributes the skill listing's tokens to each included skill. The per-skill counts measure each skill's listing entry as Claude Code actually sends it, which can be shorter than the skill's full frontmatter. Compare `skills.totalSkills` with `skills.includedSkills` to see whether every discovered skill made it into the listing.767* `skills.skillFrontmatter` attributes the skill listing's tokens to each included skill. The per-skill counts measure each skill's listing entry as Claude Code actually sends it, which can be shorter than the skill's full frontmatter. Compare `skills.totalSkills` with `skills.includedSkills` to see whether every discovered skill made it into the listing.
766 768
767`totalTokens` is the session's current context usage, and `maxTokens` is the window that usage is measured against. That window is the model's context window, or the lower auto-compaction window when one applies. Claude Code leaves the optional `deferredBuiltinTools`, `systemTools`, and `systemPromptSections` diagnostics unset, so expect them to be absent even though the type declares them.769`totalTokens` is the session's current context usage, and `maxTokens` is the window that usage is measured against. That window is the model's context window, or the lower auto-compaction window when one applies. `rawMaxTokens` carries the same value as `maxTokens`, and `percentage` is `totalTokens` as a rounded percentage of that window.
770
771Claude Code leaves the optional `deferredBuiltinTools`, `systemTools`, and `systemPromptSections` diagnostics unset, so expect them to be absent even though the type declares them.
768 772
769### `SDKControlReadFileResponse`773### `SDKControlReadFileResponse`
770 774
1144 error?: SDKAssistantMessageError;1148 error?: SDKAssistantMessageError;
1145 aborted?: true;1149 aborted?: true;
1146 timestamp?: string;1150 timestamp?: string;
1151 context_usage?: SDKContextUsage;
1147};1152};
1148```1153```
1149 1154
1155 1160
1156`timestamp` is the ISO 8601 time when the message's content finished generating on the process that produced it. The value comes from that machine's clock, so use it for display only and don't order messages by it. One API turn can produce several assistant messages that share a `message.id`, each with its own `timestamp`. When the field is absent, fall back to the time you received the message.1161`timestamp` is the ISO 8601 time when the message's content finished generating on the process that produced it. The value comes from that machine's clock, so use it for display only and don't order messages by it. One API turn can produce several assistant messages that share a `message.id`, each with its own `timestamp`. When the field is absent, fall back to the time you received the message.
1157 1162
1163`context_usage` is a structured copy of the `/context` report, typed as [`SDKContextUsage`](#sdkcontextusage), and requires Agent SDK v0.3.232 or later. When you send `/context` as a prompt, Claude Code delivers the report as an assistant message whose `message.content` holds the markdown table, and attaches `context_usage` to that same message. Claude Code doesn't set the field on any other assistant message, and earlier versions deliver the `/context` table without it, so read the breakdown from the field when it's present and fall back to the markdown text when it isn't.
1164
1158### `SDKUserMessage`1165### `SDKUserMessage`
1159 1166
1160User input message.1167User input message.
1464};1471};
1465```1472```
1466 1473
1474### `SDKContextUsage`
1475
1476Structured form of the `/context` report, carried as `context_usage` on the [`SDKAssistantMessage`](#sdkassistantmessage) that delivers a `/context` result. Agent SDK v0.3.232 and later export the type. Unlike [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse), it carries only the data needed to render the usage breakdown, without display fields such as `color` and `gridRows`.
1477
1478```typescript theme={null}
1479type SDKContextUsage = {
1480 model: string;
1481 total_tokens: number;
1482 raw_max_tokens: number;
1483 percentage: number;
1484 over_limit?: {
1485 tokens_over: number;
1486 kind: "hard_limit" | "compaction_window";
1487 };
1488 categories: SDKContextUsageCategory[];
1489 mcp_tools: {
1490 name: string;
1491 server_name: string;
1492 tokens: number;
1493 }[];
1494 memory_files: {
1495 path: string;
1496 type: string;
1497 tokens: number;
1498 }[];
1499 agents: {
1500 agent_type: string;
1501 source: string;
1502 tokens: number;
1503 }[];
1504 skills?: {
1505 name: string;
1506 source: string;
1507 plugin_name?: string;
1508 tokens: number;
1509 }[];
1510};
1511```
1512
1513The table lists what Claude Code puts in each field. The fields from `model` through `over_limit` describe the session as a whole, and the collection fields attribute tokens to individual items.
1514
1515| Field | Type | Description |
1516| ---------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1517| `model` | `string` | The main loop's model Claude Code computed the usage for, not a subagent's |
1518| `total_tokens` | `number` | Claude Code's estimate of the tokens in use. Not clamped to the window, so it can exceed `raw_max_tokens` when the session is over the limit |
1519| `raw_max_tokens` | `number` | The model's context window, or the lower [auto-compact window](/docs/en/model-config#context-window-and-auto-compaction) when one applies, such as one you set or the 200K boundary Claude Code applies to some models with a 1M-token window. Claude Code measures `total_tokens` against this window |
1520| `percentage` | `number` | `total_tokens` as a rounded percentage of `raw_max_tokens`, so it can exceed 100 when the session is over the limit |
1521| `over_limit` | `object` | Present only when `total_tokens` exceeds `raw_max_tokens`. `tokens_over` is the amount over, and `kind` says how Claude Code resolved the window |
1522| `categories` | [`SDKContextUsageCategory`](#sdkcontextusagecategory)`[]` | One entry per row of the usage-by-category breakdown |
1523| `mcp_tools` | `object[]` | Tokens attributed to each MCP tool, with its wire name, such as `mcp__linear__create_issue`, and its `server_name` |
1524| `memory_files` | `object[]` | Tokens attributed to each loaded memory file, with its `path` and a source label such as `Project` or `User` in `type` |
1525| `agents` | `object[]` | Tokens attributed to each custom subagent definition, with a source identifier such as `projectSettings`, `userSettings`, or `plugin`. Built-in subagents aren't listed |
1526| `skills` | `object[]` | Tokens attributed to each skill in the skill listing, with a source identifier and, for plugin skills, the plugin's name in `plugin_name`. Absent when no skills contribute tokens |
1527
1528`over_limit.kind` records how Claude Code resolved the window, not whether the API accepts the next request:
1529
1530* `hard_limit`: the window is what Claude Code believes to be the model's own limit, past which the API refuses requests
1531* `compaction_window`: the window is a compaction-policy window, which may or may not coincide with the model's limit
1532
1533Claude Code evolves the type additively, adding new data as optional fields rather than reshaping existing ones. Read the fields you know and ignore any you don't recognize.
1534
1535### `SDKContextUsageCategory`
1536
1537One row of the `/context` usage-by-category breakdown.
1538
1539```typescript theme={null}
1540type SDKContextUsageCategory = {
1541 name: string;
1542 tokens: number;
1543 kind: "used" | "free" | "buffer" | "deferred";
1544};
1545```
1546
1547The table lists what Claude Code puts in each field of a row.
1548
1549| Field | Type | Description |
1550| -------- | -------- | -------------------------------------------------------------------------------------------------------- |
1551| `name` | `string` | The row's display name as `/context` prints it, such as `Messages`. Classify rows by `kind`, not by name |
1552| `tokens` | `number` | The row's token count. Rows can carry zero tokens |
1553| `kind` | `string` | What the row represents: `used`, `free`, `buffer`, or `deferred` |
1554
1555Each `kind` value says what the row's tokens are:
1556
1557* `used`: content that occupies the context window
1558* `free`: the remaining window
1559* `buffer`: the compaction reserve
1560* `deferred`: tool schemas Claude Code holds out of the window and excludes from the usage calculation, listed for awareness
1561
1467### `SDKMessageOrigin`1562### `SDKMessageOrigin`
1468 1563
1469Provenance of a user-role message. This appears as `origin` on [`SDKUserMessage`](#sdkusermessage) and is forwarded onto the corresponding [`SDKResultMessage`](#sdkresultmessage) so you can tell what triggered a given turn.1564Provenance of a user-role message. This appears as `origin` on [`SDKUserMessage`](#sdkusermessage) and is forwarded onto the corresponding [`SDKResultMessage`](#sdkresultmessage) so you can tell what triggered a given turn.
