---
title: "List a Reason's messages"
method: GET
path: "/v3/organizations/{orgId}/reasons/{reasonId}/messages"
tags: ["Reasons"]
---

# List a Reason's messages

`GET /v3/organizations/{orgId}/reasons/{reasonId}/messages`

## Request

- Base URL: `https://api.reasonmachines.com`
- URL: `https://api.reasonmachines.com/v3/organizations/{orgId}/reasons/{reasonId}/messages`
- Auth: HTTP bearer

Returns the Reason's conversation in order, as listSessionConversation returns its conversation Session's: the opening prompt, each message sent to it, and one reply for every finished turn, failed or cancelled turns included, with `kind` telling them apart. The page is empty, with `session_id` null, until the conversation is opened by its first message. Cursor-paginated: pass `end_cursor` as `after`, and keep polling with it to receive the Reason's next reply. Readable by the Reason's owner and the people it is shared with.

<sub>Scope: `sessions:read`</sub>

## Query parameters

- `first` integer
- `after` string

## Response `200`

A page of the Reason's conversation.

- ReasonMessagePage
  - `items` ConversationItem[], required
    - `id` string, required: Identifies the item across reads.
    - `cursor` integer, required: Where a reader stands after this item: pass it as `after` to read what follows. Cursors strictly increase through the list. It is a position in this list only, not a message `seq`, and the same item can carry a different cursor in a later read; use `id` to recognise an item.
    - `kind` 'prompt' | 'message' | 'reply', required: `prompt` is the Session's opening prompt, `message` a message in the conversation afterwards, `reply` how a finished turn ended.
    - `role` string, required: `user` for the prompt and for a message sent to the Session; `assistant` for a reply, and for a message the agent posted outside a turn's reply (a greeting or a notice).
    - `content` string, required: For a reply, the turn's `result_summary`; empty when the turn left none.
    - `status` string: Replies only: how the turn ended, in the values of the Session's `status`.
    - `outcome` 'success' | 'failure' | 'action_required', nullable: Replies only: the turn's outcome, as the Session's `outcome` reports it for the latest turn. Null when the turn did not succeed and declared none, for example a failed or cancelled turn.
    - `metadata` object
      - `source` 'subagent', required: An automatic child result, not a human follow-up.
    - `attachments` object[]: Messages only. Files attached to the opening prompt are not listed here; list them with listSessionAttachments.
    - `created_at` string, date-time, nullable
  - `has_next_page` boolean, required
  - `end_cursor` string, nullable, required: The cursor of the last item, or the `after` that was sent when the page is empty; null only when nothing has been read. Keep polling with it after `has_next_page` is false to receive what is said next.
  - `reason_id` string, uuid, required: The Reason whose conversation this is.
  - `session_id` string, nullable, required: The Reason's conversation Session; null, with no items, until its first message opens it.

## Other responses

- `400`: `after` is not a cursor this list could have issued (`invalid_cursor`).
- `401`: Missing, invalid, or expired key.
- `403`: The key lacks the required scope or role.
- `404`: Resource not found.
- `429`: Too many requests. Retry after the number of seconds in the `Retry-After` response header.

## Changes

- **2026-10-26** `c250866428e0`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ara/apis/reason-api/changes/v3/organizations/:orgId/reasons/:reasonId/messages/get.md)

---

[API](https://skmtc.dev/ara/apis/reason-api.md) - [All operations](https://skmtc.dev/ara/apis/reason-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ara/apis/reason-api/revisions/e97c8704807c?raw)