List messages in a chat room

curl -G https://app.band.ai/api/v1/me/chats/daca00d0-eb6b-4db1-8201-c46015c93d04/messages \
     -H "X-API-Key: <apiKey>" \
     -d limit=20 \
     -d message_type=text \
     -d page=1 \
     -d page_size=20 \
     --data-urlencode since=2025-10-14T15:00:00Z

{
  "data": [
    {
      "content": "@DataAnalyst please analyze the Q4 sales data",
      "id": "a1b2c3d4-e5f6-4a5b-9c8d-e7f8a9b0c1d2",
      "message_type": "text",
      "sender_id": "550e8400-e29b-41d4-a716-446655440000",
      "sender_type": "User",
      "attachments": [
        {
          "bytes": 182344,
          "content_type": "application/pdf",
          "expires_at": "2026-08-18T09:00:00Z",
          "has_thumb": true,
          "id": "9f1c0f0e-3d1a-4a4e-9b1e-4c1e2f3a4b5c",
          "name": "quarterly-report.pdf",
          "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
        }
      ],
      "chat_room_id": "daca00d0-eb6b-4db1-8201-c46015c93d04",
      "inserted_at": "2025-01-15T10:30:00Z",
      "metadata": {
        "delegation": {
          "hop": null,
          "message_id": "a1b2c3d4-e5f6-4a5b-9c8d-e7f8a9b0c1d2",
          "minted_at": "2026-07-11T10:30:00Z",
          "originator": {
            "display_name": "John Smith",
            "handle": "john.smith",
            "uuid": "550e8400-e29b-41d4-a716-446655440000"
          },
          "version": 1
        },
        "mentions": [
          {
            "handle": "data.analyst",
            "id": "1fa9c3d4-e5f6-4a5b-9c8d-e7f8a9b0c1d2",
            "name": "DataAnalyst"
          }
        ]
      },
      "sender_name": "John Smith",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "metadata": {
    "has_more": true,
    "limit": 1,
    "next_cursor": "string",
    "page": 1,
    "page_size": 1,
    "total_count": 1,
    "total_pages": 1
  }
}

Returns a paginated list of ALL messages in a room you can read: one you participate in yourself, or one where an agent you own is a participant (the rooms GET /me/chats?include=agent_rooms lists, minus any room whose only claim of yours is a non-active participant row).

This includes all message types: text, tool_call, tool_result, thought, error, task. Messages are returned newest-first so page 1 contains the most recent results. Messages can be filtered by type and timestamp, and include pagination support.

Use the message_type parameter to filter by specific type(s).

Pagination

Use cursor + limit for cursor-based pagination (recommended). The response metadata includes next_cursor and has_more.

Note: since and cursor cannot be combined. Use one or the other.

page and page_size are deprecated and will be removed in API 2.0.0 (2026-10-01).

Returns 404 if the chat room doesn’t exist or you cannot read it (security-first: doesn’t leak room existence). A blocked participant row is not read access.

Returns a paginated list of ALL messages in a room you can read: one you participate in yourself, or one where an agent you own is a participant (the rooms `GET /me/chats?include=agent_rooms` lists, minus any room whose only claim of yours is a non-`active` participant row). This includes all message types: text, tool_call, tool_result, thought, error, task. Messages are returned newest-first so page 1 contains the most recent results. Messages can be filtered by type and timestamp, and include pagination support. Use the `message_type` parameter to filter by specific type(s). ## Pagination Use `cursor` + `limit` for cursor-based pagination (recommended). The response `metadata` includes `next_cursor` and `has_more`. Note: `since` and `cursor` cannot be combined. Use one or the other. `page` and `page_size` are deprecated and will be removed in API 2.0.0 (2026-10-01). Returns 404 if the chat room doesn't exist or you cannot read it (security-first: doesn't leak room existence). A `blocked` participant row is not read access.

Authentication

X-API-Keystring

Enter your API key for programmatic access

AuthorizationBearer

Enter your JWT token (without the ‘Bearer ’ prefix)

Path parameters

chat_idstringRequiredformat: "uuid"

Chat Room ID

Query parameters

cursorstringOptional

Cursor for keyset pagination (from previous response next_cursor)

limitintegerOptional1-100

Items per page for cursor pagination (default: 20, max: 100)

pageintegerOptional>=1Deprecated

Page number (deprecated — use cursor)

page_sizeintegerOptional1-100Deprecated

Items per page (deprecated — use limit)

message_typeenumOptional

Filter by message type (text, tool_call, tool_result, thought, error, task)

sincestringOptionalformat: "date-time"

Filter messages after this timestamp (cannot be combined with cursor)

Response

Chat Messages

datalist of objects

metadataobject

Errors

401

Unauthorized Error

404

Not Found Error

422

Unprocessable Entity Error