Get Session Context (Extension)
Read the latest context measurement and the currently selected model’s window and compaction thresholds.
/agent/v1/sessions/{session_id}/context● SupportedRequest parameters
session_idstring必填path: Session id (sesn_...), as returned by sessions.create or sessions.list. The same id is also accepted as the session_id query parameter on resource and thread calls, where it must equal the path value.
Returns
200
Praxis extension available only on /agent/v1, following Claude Agent SDK getContextUsage() with snake_case fields. detail is summary: the latest actual model usage takes precedence, and local estimates apportion source totals; used categories sum to total_tokens. Only nonzero sources appear. Classify rows by kind (used/free/buffer/deferred). key is a stable source identifier extension; clients must tolerate unknown keys and new sources, falling back to name. MCP tools group by server, plugin blocks by id, and compaction summaries are counted separately. excluded_items is currently zero. Before measurement, total_tokens, total_tokens_source and measured_at are null, categories is empty, and details are zero or empty arrays. Model selection recalculates max_tokens, auto_compact_threshold and free/buffer while preserving the latest measurement. is_auto_compact_enabled is false for unknown capacity or a tripped compaction breaker. For example model.thinking is {efforts: [high, xhigh], can_disable: true, default_effort: high}. model.thinking contains efforts, can_disable and nullable default_effort; the entire thinking value is null when capability is unknown. Missing or inaccessible sessions return 404.
Errors follow the Anthropic error format (type / message / request_id) — see error codes
Response
HTTP 200
Current model and latest context measurement
application/json
| Name | Type | Description |
|---|---|---|
| type | string | Always `session_context`. Snapshot of a session's context window usage. |
| session_id | string | Session whose context this snapshot describes. |
| model | object | Model of the session and its context window facts. |
| model.id | string | Identifier of the object, as returned by the API; pass it in the path of follow-up calls on the same resource. |
| model.display_name | string | Human-readable name of the model. |
| model.thinking | object | null | Thinking capability of the model: supported efforts, whether thinking can be disabled, and the default. Null when the capability is unknown. |
| total_tokens | number | null | Tokens currently occupying the context window; null before the first measurement. |
| total_tokens_source | string | null | Whether total_tokens is the provider-reported input usage (actual) or a local estimate (estimated); null before the first measurement. |
| max_tokens | number | null | Context window of the model in tokens; null when the model does not state one. |
| max_input_tokens | number | null | Maximum input tokens the model accepts per request; null when not stated. |
| percentage | number | Share of the context window in use, as a whole-number percent; 0 when the window or usage is unknown. |
| auto_compact_threshold | number | null | Token count at which automatic compaction starts; null when the window is unknown. |
| is_auto_compact_enabled | boolean | Whether automatic compaction is enabled for this session. |
| clear_tool_results_at | number | Token count at which old tool results are cleared from the context. |
| detail | string | Level of detail of the snapshot. |
| categories | array<object> | Context usage by category; each row has a stable key and a kind. |
| categories[].key | string | Praxis extension: stable source identifier (system, tools, mcp:<server>, plugin:<id>, messages, summary, free, buffer). Clients must tolerate unknown keys and newly added sources; classify rows by kind, not key or name. |
| categories[].name | string | Display name of the category. |
| categories[].tokens | number | Tokens used by the category. |
| categories[].kind | string | How the category counts against the window. |
| mcp_tools | array<object> | Tokens spent on the tool definitions of each MCP server. |
| mcp_tools[].name | string | Name of the MCP tool. |
| mcp_tools[].server_name | string | Name of the MCP server that provides the tool. |
| mcp_tools[].tokens | number | Tokens used by the tool definition. |
| plugin_blocks | array<object> | Tokens spent on context blocks injected by each mod. |
| plugin_blocks[].name | string | Name of the mod that injected the block. |
| plugin_blocks[].tokens | number | Tokens used by the block. |
| message_breakdown | object | Tokens in the conversation messages, split by role and tool traffic. |
| message_breakdown.user_message_tokens | number | Tokens of user messages. |
| message_breakdown.assistant_message_tokens | number | Tokens of assistant text messages. |
| message_breakdown.tool_call_tokens | number | Tokens of tool-call arguments. |
| message_breakdown.tool_result_tokens | number | Tokens of tool results. |
| message_breakdown.reasoning_tokens | number | Tokens of reasoning content. |
| message_breakdown.tool_calls_by_type | array<object> | Tool-call and tool-result tokens grouped by tool name. |
| compaction_summary | object | null | Tokens held by the latest compaction summary; null when the session was never compacted. |
| compaction_summary.tokens | number | Tokens of the compaction summary. |
| excluded_items | object | Items removed from the context for content safety, kept for audit only and not counted as usage. |
| excluded_items.count | number | Number of excluded items. |
| excluded_items.tokens | number | Tokens of the excluded items. |
| measured_at | string | null | RFC 3339 time of the measurement; null before the first measurement. |