agents

List Messages

Retrieve message history for an agent.

get/v1/agents/{agent_id}/messages

Request

agent_idstring required

beforestring nullable

Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order

afterstring nullable

Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order

limitinteger nullable

Maximum number of messages to return

order'asc' | 'desc'

Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first

order_by'created_at'

Field to sort by

group_idstring nullable

Group ID to filter messages by.

use_assistant_messageboolean

Whether to use assistant messages

assistant_message_tool_namestring

The name of the designated message tool.

assistant_message_tool_kwargstring

The name of the message argument.

include_errboolean nullable

Whether to include error messages and error statuses. For debugging purposes only.

Successful Response

Oct 8, 2025b82cbf314740 Revision changes
- info
  added the optional property // to the response with the status
- info
  response property items/oneOf[subschema #5: ToolCallMessage]/tool_call deprecated
Oct 8, 20251bed3816dfe2 Revision changes
- info
  added the optional property // to the response with the status
- info
  response property items/oneOf[subschema #6: ToolReturnMessage]/status deprecated
- info
  response property items/oneOf[subschema #6: ToolReturnMessage]/stderr deprecated
- info
  response property items/oneOf[subschema #6: ToolReturnMessage]/stdout deprecated
- info
  response property items/oneOf[subschema #6: ToolReturnMessage]/tool_call_id deprecated
- info
  response property items/oneOf[subschema #6: ToolReturnMessage]/tool_return deprecated