v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

List messages in a thread

Returns a cursor-paginated list of messages belonging to the specified thread, ordered from oldest to newest. Supply before_cursor or after_cursor (not both) to page through the result set; omit both to receive the most recent page.

The authenticated user must have access to the thread's owner (workspace or user). A 403 is returned if the thread exists but is not accessible to the caller; a 404 is returned if the thread does not exist or is not visible to the authenticated user.

Pass include_reply_counts: true to annotate each message with the number of threaded replies it has received. This adds a small amount of latency and should be omitted when reply counts are not needed.

get/api/v1/threads/{thread}/messages

Path parameters

threadstring required

Thread ID (thr_...). The authenticated user must have access to this thread.

Query parameters

limitinteger

Maximum number of messages to return per page. Defaults to 20.

after_cursorstring

Opaque cursor returned in a previous response's after_cursor field. When provided, returns the page of messages immediately after that position. Cannot be combined with before_cursor.

before_cursorstring

Opaque cursor returned in a previous response's before_cursor field. When provided, returns the page of messages immediately before that position. Cannot be combined with after_cursor.

include_reply_countsboolean

When true, each message in the response is annotated with its threaded reply count. Defaults to false. Adds latency; omit when reply counts are not needed.

Response

Successful response

Example response

{
  "data": {
    "after_cursor": "string",
    "before_cursor": "string",
    "messages": [
      {
        "actors": [
          {
            "alias": "alice",
            "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
            "name": "Example Name",
            "profile_picture": {
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "height": 600,
              "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
              "mime_type": "application/json",
              "refresh_url": "https://example.com",
              "url": "https://example.com",
              "width": 800
            }
          }
        ],
        "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
        "attachments": [
          {
            "content_type": "application/json",
            "description": "An example description.",
            "filename": "string",
            "height": 1,
            "id": "string",
            "image_height": 1,
            "image_source": {
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "height": 600,
              "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
              "mime_type": "application/json",
              "refresh_url": "https://example.com",
              "url": "https://example.com",
              "width": 800
            },
            "image_url": "https://example.com",
            "image_width": 1,
            "media_type": "application/json",
            "name": "Example Name",
            "object": {},
            "title": "Example Title",
            "type": "file",
            "url": "https://example.com",
            "variants": [
              {
                "content_type": "application/json",
                "created_at": "2024-01-01T00:00:00Z",
                "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
                "filename": "string",
                "height": 600,
                "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
                "image_source": {
                  "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
                  "height": 600,
                  "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
                  "mime_type": "application/json",
                  "refresh_url": "https://example.com",
                  "url": "https://example.com",
                  "width": 800
                },
                "updated_at": "2024-01-01T00:00:00Z",
                "url": "https://example.com",
                "variant_key": "original",
                "width": 800
              }
            ],
            "version": 1,
            "width": 1
          }
        ],
        "branched_thread": "string",
        "content": "Hello, how can I help you today?",
        "created_at": "2024-01-01T00:00:00Z",
        "has_replies": true,
        "id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
        "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
        "legacy_agent": "string",
        "metadata": {
          "key": "value"
        },
        "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
        "reactions": [
          {
            "payload": {
              "key": "value"
            },
            "type": "emoji_reaction",
            "user": "string"
          }
        ],
        "rendering_mode": "reply",
        "replies": [
          {}
        ],
        "replies_after_cursor": "string",
        "replies_before_cursor": "string",
        "reply_count": 1,
        "reply_to": {},
        "sandbox": "string",
        "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
        "thread": "string",
        "user": "string"
      }
    ]
  }
}