v106

OpenAPI 3.1.0raw.githubusercontent.com2026-08-02160524464.6 KB

Run Internals

Get Stage Context Window

Returns the latest best-effort model-visible context-window usage snapshot for an agent stage. Known stages without applicable or observed data return available: false; missing runs or stages return 404.

get/api/v1/runs/{id}/stages/{stageId}/context-window

Path parameters

idstring required

Unique run identifier (ULID).

stageIdstring required

Identifier of a stage within a run's workflow graph, serialized as node_id@visit.

Response

Latest context-window snapshot or a typed unavailable state.

stage_idstring required

Stage ID in node@visit form.

availableboolean required

Whether context-window data is available for this known stage.

unavailable_reason'not_agent_stage' | 'not_observed' | 'provider_unconfigured' required

Why context-window data is unavailable for a known run stage.

providerstring nullable required

modelstring nullable required

context_window_tokensinteger nullable required

input_tokensinteger nullable required

usage_percentnumber double nullable required

count_method'provider_api_scaled_breakdown' | 'response_usage_scaled_breakdown' | 'local_estimate' required

Method used to produce the context-window token total and breakdown.

staleness'live' | 'stored' | 'unavailable' required

Freshness of the returned context-window data.

generated_atstring date-time nullable required

event_seqinteger nullable required

Example response

{
  "stage_id": "implement@1",
  "provider": "openai",
  "model": "gpt-5.4",
  "context_window_tokens": 400000,
  "input_tokens": 123456,
  "usage_percent": 30.86,
  "generated_at": "2026-05-23T12:34:56Z",
  "event_seq": 42,
  "breakdown": [
    {
      "tokens": 30000,
      "usage_percent": 7.5
    }
  ],
  "warnings": [
    {
      "code": "provider_token_count_failed",
      "message": "provider input token counting failed; returned local estimate"
    }
  ]
}