---
title: "List messages in a thread"
method: GET
path: "/api/v1/threads/{thread}/messages"
---

# List messages in a thread

`GET /api/v1/threads/{thread}/messages`

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.

## Path parameters

- `thread` string, required

## Query parameters

- `limit` integer
- `after_cursor` string
- `before_cursor` string
- `include_reply_counts` boolean

## Response `200`

Successful response

- object — Paginated list of messages for the requested thread.
  - `data` object, required — Pagination envelope containing the messages for this page along with cursors for adjacent pages.
    - `after_cursor` string — Opaque cursor to pass as `after` to retrieve the page of messages newer than this result set. `null` when there are no later messages.
    - `before_cursor` string — Opaque cursor to pass as `before` to retrieve the page of messages older than this result set. `null` when there are no earlier messages.
    - `messages` object[], required — Ordered array of message objects for this page of results.
      - `actors` object[] — Resolved actor descriptors for the message sender, combining identity and display metadata. Always contains exactly one entry.
        - `alias` string — Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.
        - `id` string — Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.
        - `name` string — Display name of the actor shown in the UI. `null` if no name is set.
        - `profile_picture` object — Profile picture for the actor. `null` if the actor has no profile picture.
          - `file` string — ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.
          - `height` integer — Height of the image in pixels. `null` if not known.
          - `media` string — ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.
          - `mime_type` string — MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.
          - `refresh_url` string — Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.
          - `url` string — Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.
          - `width` integer — Width of the image in pixels. `null` if not known.
      - `agent` string — ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.
      - `attachments` object[] — Files, links, tasks, media, artifacts, and actions attached to this message. Empty array if there are no attachments.
        - `content_type` string — MIME type of the attached file, e.g. `"image/png"` or `"application/pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.
        - `description` string — Short description. The page meta-description for `scraped_link`, the artifact description for `artifact`, and the task description for `task` types. `null` on other types.
        - `filename` string — Original filename of the attached file, e.g. `"report.pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.
        - `height` integer — Height in pixels of the media item. Present on `media` type only. `null` otherwise.
        - `id` string, required — Unique identifier for this attachment within the message.
        - `image_height` integer — Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.
        - `image_source` object — Image source metadata for inline rendering. Present on `file`, `scraped_link`, `artifact`, and `media` types when the content is an image. `null` otherwise.
          - `file` string — ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.
          - `height` integer — Height of the image in pixels. `null` if not known.
          - `media` string — ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.
          - `mime_type` string — MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.
          - `refresh_url` string — Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.
          - `url` string — Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.
          - `width` integer — Width of the image in pixels. `null` if not known.
        - `image_url` string — URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.
        - `image_width` integer — Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.
        - `media_type` string — The media category, e.g. `"video"` or `"audio"`. Present on `media` type only. `null` otherwise.
        - `name` string — Display name of the media item. Present on `media` type only. `null` otherwise.
        - `object` object — The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. `null` on other types.
        - `title` string — Display title. The page title for `scraped_link`, the artifact name for `artifact`, and the task title for `task` types. `null` on other types.
        - `type` string, required — The attachment type. One of `"file"`, `"scraped_link"`, `"artifact"`, `"task"`, `"media"`, or `"action"`. Determines which additional fields are present.
        - `url` string — URL to access the resource. A signed download URL for `file` and `artifact` types; the original URL for `scraped_link`; a media playback URL for `media`. `null` on `task` and `action` types.
        - `variants` object[] — Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise.
          - `content_type` string — MIME type of this variant's file (e.g., `"image/jpeg"`, `"video/mp4"`). `null` if the file is not loaded.
          - `created_at` string, date-time — When this variant was created (ISO 8601).
          - `file` string — ID of the underlying storage file that backs this variant (`fil_...`).
          - `filename` string — Original filename of the uploaded file for this variant. `null` if the file is not loaded.
          - `height` integer — Height of this variant in pixels. `null` if not recorded.
          - `id` string, required — Media variant ID (`mvr_...`).
          - `image_source` object — Resolved image delivery metadata for this variant, including dimensions and CDN URL. `null` for non-image content types.
            - `file` string — ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.
            - `height` integer — Height of the image in pixels. `null` if not known.
            - `media` string — ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.
            - `mime_type` string — MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.
            - `refresh_url` string — Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.
            - `url` string — Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.
            - `width` integer — Width of the image in pixels. `null` if not known.
          - `updated_at` string, date-time — When this variant was last updated (ISO 8601).
          - `url` string — Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.
          - `variant_key` string — Identifier for this variant's processing tier. Common values include `"original"` (the unmodified upload) and `"thumbnail"` (a resized preview).
          - `width` integer — Width of this variant in pixels. `null` if not recorded.
        - `version` integer — Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.
        - `width` integer — Width in pixels of the media item. Present on `media` type only. `null` otherwise.
      - `branched_thread` string — ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.
      - `content` string — Text content of the message. `null` for messages that contain only attachments.
      - `created_at` string, date-time — When the message was posted (ISO 8601).
      - `has_replies` boolean — Whether this message has at least one reply. Only present when explicitly requested or computed by the server.
      - `id` string, required — Message ID (`msg_...`).
      - `idempotency_key` string — Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.
      - `legacy_agent` string — Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.
      - `metadata` object — Arbitrary key-value metadata attached to the message. Always present; defaults to an empty object when no metadata has been set.
      - `org` string — ID of the organization that owns this message (`org_...`).
      - `reactions` object[] — Emoji and other reactions added to this message by users. Empty array if no reactions have been added or the association is not preloaded.
        - `payload` object — Type-specific reaction data. For `"emoji_reaction"` reactions, contains an `emoji` key with the Unicode emoji string (e.g., `"👍"`).
        - `type` string, required — Reaction type identifier. Currently always `"emoji_reaction"` for emoji-based reactions.
        - `user` string — Public ID of the user who added the reaction (`usr_...`).
      - `rendering_mode` string — Display hint for how the message should be rendered. One of `"reply"`, `"direct"`, or `"inline"`. `null` for user-authored messages, which are always rendered as standard replies.
      - `replies` object[] — Inline array of reply messages, each serialized as a full message object. Only present when the server has preloaded replies for this message.
      - `replies_after_cursor` string — Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.
      - `replies_before_cursor` string — Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.
      - `reply_count` integer — Total number of direct replies to this message. Only present when explicitly requested or computed by the server.
      - `reply_to` object — The parent message this message is a reply to, expanded as a full message object when loaded. `null` if this is a top-level message or the association is not preloaded.
      - `sandbox` string — ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.
      - `team` string — ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.
      - `thread` string — ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread.
      - `user` string — The human user who sent this message. Returns a public ID string (`usr_...`) when the association is not preloaded, or an expanded user object when it is. `null` for messages sent by agents.

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Thread not found

---

[API](https://skmtc.net/archastro/apis/archastro-platform-api.md) · [All operations](https://skmtc.net/archastro/apis/archastro-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/archastro/archastro-platform-api/versions/a8772b442f86/schema)