The session object

⚠️

Preview — this feature is being built; the design below is the spec.

The session object as the API returns it. Every field below appears in every response that returns this object; fields with no value are null rather than missing.

Example

{
  "id": "sesn_01JC7M2K4P6R8T0V2X4Z",
  "type": "session",
  "agent_id": "agt_01JC4R8W6Q2N9X3T5V7Y",
  "agent_version": 4,
  "status": "requires_action",
  "channel": "api",
  "title": "Refund for order 88123",
  "usage": {
    "input_tokens": 0,
    "cached_input_tokens": 0,
    "output_tokens": 0,
    "cost_usd": "0.0000"
  },
  "outcome": null,
  "created_at": "2026-11-05T10:00:00Z",
  "last_event_at": "2026-11-05T10:00:00Z",
  "metadata": {}
}

Fields

Field	Type	Description
`id`	string	Starts with `sesn_`.
`type`	string	The object type, always `session`.
`agent_id`	string	The agent the session runs.
`agent_version`	integer	The version it is pinned to for its whole life.
`status`	string	`running`, `requires_action` (waiting for your tool result or approval), `idle` or `archived`.
`channel`	string	`api` for sessions started here; channel sessions show `telegram`, `slack` and so on.
`title`	string or null	The new title.
`usage`	object	Running token and cost totals.
`outcome`	object or null	Set when a turn ends: `reason` is `end_turn`, `max_turns`, `budget_exhausted`, `interrupted` or `error`.
`created_at`	string	When it was created, RFC 3339 UTC (some older objects use Unix seconds).
`last_event_at`	string	Time of the latest event.
`metadata`	object	The merged map after the update.

Returned by

service_account session_resource

Was this page helpful?