list_ai_chat_messages¶

ArtificialIntelligenceApi.list_ai_chat_messages(chat_id, role_id, sortby=None, sortorder=None, limit=None, offset=None, filter_expression=None, projection_expression=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)¶

List chat messages

Returns a paginated list of messages for the chat. Requires at least read-only access. Default offset is 1 (1-based), limit 5000 (max 5000), sortby MessageTime, sortorder asc (unlike chat list, which defaults to desc). Optional filterExpression (Content supports wildcards) and projectionExpression. Chart Content is replaced with a presigned plot URL. Code-generator chats (chat_id starts with {user_id}-) use job access. No request body.

Parameters:

chat_id (str) – Unique identifier of the chat. (required)
role_id (str) – Amorphic role ID of the requesting user. Must be a role the authenticated user belongs to. (required)
sortby (str) – Field to sort by. Default MessageTime. The field must exist on every message item.
sortorder (str) – Sort direction. Default asc for messages. Any value other than desc is treated as ascending.
limit (int) – Page size. Default 5000, maximum 5000.
offset (int) – 1-based page offset. Default 1. Values below 1 are treated as page 1.
filter_expression (str) – Comma-separated field:value filters applied before pagination (format key:value). Content supports wildcard matching.
projection_expression (str) – Comma-separated message attributes to include. When omitted, all returned fields are included.
_request_timeout (int, tuple(int, int), optional) – timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of (connection, read) timeouts.
_request_auth (dict, optional) – set to override the auth_settings for an a single request; this effectively ignores the authentication in the spec for a single request.
_content_type (str, Optional) – force content-type for the request.
_headers (dict, optional) – set to override the headers for a single request; this effectively ignores the headers in the spec for a single request.
_host_index (int, optional) – set to override the host_index for a single request; this effectively ignores the host_index in the spec for a single request.

Return type:

ChatMessagesResponse

Returns:

Returns the result object.

Request and Response Examples¶

HTTP: GET /ai/playground/chats/{chat_id}/messages

Parameter examples¶

Name	In	Example
`chat_id`	path	`"123e4567-e89b-12d3-a456-426614174000"`
`role_id`	header	`"custom-role-123e4567-e89b-12d3-a456-426614174000"`
`filterExpression`	query	`"Type:user"`
`projectionExpression`	query	`"MessageTime,Type,Content,ContentType"`

Success (HTTP 200)¶

Paginated messages plus next_available, count, and total_count. Stop when next_available is “no”.

Request / response example

{
  "messages": [
    {
      "ChatId": "123e4567-e89b-12d3-a456-426614174000",
      "MessageTime": "2026-08-19 10:00:00",
      "Type": "user",
      "ContentType": "text",
      "Content": "What were Q2 sales highlights?"
    },
    {
      "ChatId": "123e4567-e89b-12d3-a456-426614174000",
      "MessageTime": "2026-08-19 10:00:01",
      "Type": "ai",
      "ContentType": "text",
      "Content": "Q2 revenue increased 12% year over year.",
      "ModelId": "anthropic.claude-sonnet-4-6"
    }
  ],
  "next_available": "no",
  "count": 2,
  "total_count": 2
}

Errors¶

Documented error codes: IPV-1050, IPV-1002, AUTH-1001, AUTH-1011, GE-1008, DB-1002.

HTTP 400

Input validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. Codes: IPV-1050 (limit over maximum), IPV-1002 (chat not found), AUTH-1001 (missing role_id), AUTH-1011 (caller not authorized).

Missing role_id header

{
  "Message": "AUTH-1001 - Missing role information in event header"
}

Caller not authorized

{
  "Message": "AUTH-1011 - User does not have sufficient permission to perform this action"
}

Limit exceeds maximum

{
  "Message": "IPV-1050 - Out of range for items per page, Limit is 5000"
}

HTTP 500

Backend failure. Body is {“Message”: “<CODE> - <text>”}. Codes: GE-1008 (unexpected backend failure), DB-1002 (persistence failure).

Unexpected backend failure

{
  "Message": "GE-1008 - Could not complete the request. Please try again."
}