Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Suggested
Overview Models Agents Tools Audio & voice Production API reference

Sessions

Create an agent session
POST/agents/sessions
Delete an agent session
DELETE/agents/sessions/{session_id}
List agent sessions
GET/agents/sessions
Retrieve an agent session
GET/agents/sessions/{session_id}
Update an agent session
POST/agents/sessions/{session_id}

SessionsArtifacts

Retrieve agent session artifact content
GET/agents/sessions/{session_id}/artifacts/{artifact_id}/content
Delete an agent session artifact
DELETE/agents/sessions/{session_id}/artifacts/{artifact_id}
List agent session artifacts
GET/agents/sessions/{session_id}/artifacts
Retrieve an agent session artifact
GET/agents/sessions/{session_id}/artifacts/{artifact_id}
ModelsExpand Collapse
SessionArtifact object { id, created_at, environment_id, 5 more }

An immutable file published by a completed hosted session turn.

id: string

The immutable artifact ID.

minLength0
created_at: number

The Unix timestamp, in seconds, when the artifact was published.

formatint64
environment_id: string

The ID of the environment that produced the artifact.

minLength0
object: "agent.session.artifact"

The object type. Always agent.session.artifact.

path: string

The original absolute file path in the execution environment.

minLength0
session_id: string

The ID of the session that owns the artifact.

minLength0
size_bytes: number

The immutable artifact size in bytes.

formatint64
minimum0
turn_id: string

The ID of the completed turn that published the artifact.

minLength0
SessionArtifactDeleted object { id, deleted, object }

Confirmation that an immutable session artifact was deleted.

id: string

The ID of the deleted session artifact.

minLength0
deleted: boolean

Whether the session artifact was deleted. Always true.

object: "agent.session.artifact.deleted"

The object type. Always agent.session.artifact.deleted.

SessionsEvents

Create agent session input events
POST/agents/sessions/{session_id}/events
Stream agent session events
GET/agents/sessions/{session_id}/events

SessionsItems

List agent session items
GET/agents/sessions/{session_id}/items

SessionsSubagents

List session subagents
GET/agents/sessions/{session_id}/subagents
Retrieve a session subagent
GET/agents/sessions/{session_id}/subagents/{subagent_id}

SessionsSubagentsItems

List subagent items
GET/agents/sessions/{session_id}/subagents/{subagent_id}/items

SessionsSubagentsTurns

List subagent turns
GET/agents/sessions/{session_id}/subagents/{subagent_id}/turns
Retrieve a subagent turn
GET/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}

SessionsSubagentsTurnsItems

List subagent turn items
GET/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items

SessionsTraces

List agent session traces
GET/agents/sessions/{session_id}/traces
ModelsExpand Collapse
SessionTrace object { id, created_at, object, 2 more }
id: string

The root turn ID. Use this ID as the pagination anchor.

minLength0
created_at: number

The Unix timestamp in seconds when the root turn was created.

formatint64
object: "agent.session.trace"

The object type, which is always agent.session.trace.

otlp: map[unknown]

An OTLP JSON ExportTraceServiceRequest containing resourceSpans. Only currently published data is returned; later trace updates are not awaited.

session_id: string

The session that owns this trace.

minLength0

SessionsTurns

List agent session turns
GET/agents/sessions/{session_id}/turns
Retrieve an agent session turn
GET/agents/sessions/{session_id}/turns/{turn_id}
ModelsExpand Collapse
Turn object { id, agent_id, completed_at, 8 more }

The canonical public representation of a session turn.

id: string

The ID of the turn.

minLength0
agent_id: string

The ID of the agent that ran the turn.

minLength0
completed_at: number or null

The Unix timestamp, in seconds, when the turn reached a terminal state.

formatint64
created_at: number

The Unix timestamp, in seconds, used to order the turn by creation time. Subagent turns use their start time, falling back to completion time or the subagent opening time when the preceding timestamps are unavailable.

formatint64
error: SessionTurnError { code, message } or null

A customer-safe error. Non-null only for a failed turn.

object: "agent.session.turn"

The object type. Always agent.session.turn.

session_id: string

The ID of the session that owns the turn.

minLength0
started_at: number or null

The Unix timestamp, in seconds, when the turn started.

formatint64
status: "queued" or "in_progress" or "waiting" or 3 more

The current status of the turn.

One of the following:
"queued"

The turn is waiting to start.

"in_progress"

The turn is in progress.

"waiting"

The turn is waiting for external input.

"completed"

The turn completed successfully.

"failed"

The turn failed.

"cancelled"

The turn was cancelled.

subagent_id: string or null

The ID of the subagent that ran the turn, if applicable.

minLength0
usage: TokenUsage { input_tokens, input_tokens_details, output_tokens, 2 more } or null

Best-effort token usage for the turn, or null if unknown. Recorded usage may change.

SessionsTurnsItems

List agent session turn items
GET/agents/sessions/{session_id}/turns/{turn_id}/items