GET /v1/sessions/{session_id}/messages - List messages (PRIMARY data)

GET

/v1/sessions/{session_id}/messages

• Production API

Parameters

Path Parameters

session_id

required

string

Session ID (prefixed, e.g., sess_…)

Responses

200

List of messages

Response wrapper for list endpoints. All list endpoints return responses wrapped in a data field.

object

data

required

Array of items returned by the list operation.

Array<object>

Message - primary conversation data (API response)

object

content

required

Array of content parts

Array

One of:

unknown

Text content

object

text

required

string

type

required

string

Allowed values: text

unknown

Image content (base64 or URL)

object

base64

string | null

media_type

string | null

url

string | null

type

required

string

Allowed values: image

unknown

Image file content (reference to uploaded image by ID)

object

filename

Original filename (for display)

string | null

image_id

required

ID of the uploaded image (format: img_{32-hex})

string

Example

img_01933b5a00007000800000000000001

type

required

string

Allowed values: image_file

unknown

Tool call content (assistant requesting tool execution)

object

arguments

required

id

required

string

name

required

string

type

required

string

Allowed values: tool_call

unknown

Tool result content (result of tool execution)

object

error

string | null

result

tool_call_id

required

ID of the tool call this result corresponds to

string

type

required

string

Allowed values: tool_result

controls

One of:

null

null

object

Runtime controls (model, reasoning, etc.)

object

model_id

Model ID to use for this message (format: model_{32-hex}). Overrides session and agent model settings.

string | null

Example

model_01933b5a00007000800000000000001

reasoning

One of:

null

null

object

Reasoning configuration

object

effort

Effort level for reasoning (low, medium, high)

string | null

created_at

required

string format: date-time

id

required

Unique message ID (format: message_{32-hex})

string

Example

message_01933b5a00007000800000000000001

metadata

Message-level metadata (locale, etc.)

object | null

role

required

Message role in the conversation

string

Allowed values: system user agent tool_result

sequence

required

integer format: int32

session_id

required

Session ID this message belongs to (format: session_{32-hex})

string

Example

session_01933b5a00007000800000000000001

400

Invalid ID format

404

Session not found

500

Internal server error