Read a session's transcript

GET/o/{org}/sessions/{session}/messages
View .md

The captured transcript as the events the live stream carries (message, tool_use, tool_result, thinking, error, result), filtered and sliced on the server. A turn starts at each user message; first/last keep that many turns, then include/exclude filter by role. Available once the run has captured its transcript; before that the answer is 404 SESSION_NOT_CAPTURED.

Authenticate with an API key or a signed-in session.

Path parameters

orgstringrequired

The org's slug or id. A caller with no role in the org gets 404.

sessionstringrequired

The session's full id (execution_id).

Query parameters

includestringoptional

Comma-separated roles to keep.

excludestringoptional

Comma-separated roles to drop. Not with include.

firstintegeroptional

Keep the first N turns. Not with last.

min 1
lastintegeroptional

Keep the last N turns. Not with first.

min 1

Responses

200The transcript slice.
execution_idstringrequired
eventsarray of SessionEventoptional

Absent when the slice holds none.

8 item fields
typestringrequired
One ofmessagetool_usetool_resultthinkingerrorresult
rolestringoptional
One ofuserassistant
contentstringoptional
toolstringoptional
call_idstringoptional

Links a tool_use to its tool_result.

argsobjectoptional

A tool_use's input as the agent wrote it, e.g. command or file_path.

successbooleanoptional
outputstringoptional
400A bad filter (INVALID_FILTER): an unknown role, include with exclude, or first with last.
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
401No bearer, an unknown, revoked or expired one, or an API key on a route keys cannot call.
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
404No such session of yours (NOT_FOUND), or no transcript captured yet (SESSION_NOT_CAPTURED).
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
429The account is over its request budget, 1,800 a minute shared by the person's API keys and console on every API host (RATE_LIMITED).

The account is over its request budget, 1,800 a minute shared by the person's API keys and console on every API host (RATE_LIMITED). The error names the limit. Wait Retry-After seconds.

errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional