# Get Shared Thread Messages

Returns the messages of the thread behind a share link, for a recipient who presents the link's slug. Authorization is the **same** as opening the link via [Get Shared Thread](/api-reference/shared-threads/get-shared-thread): the slug must resolve for the caller (active org member; explicit grant for `explicit` links; not revoked or expired). Possession of the slug is required — knowing the underlying thread id is not enough — and access is strictly **read-only**. Both `view` and `fork` links may read. An unknown or unauthorized link returns `404`.

## Authentication

Requires **user** authentication (Bearer token). API-key authentication is rejected with `403`.

## Path Parameters

**`slug`** string required

The share-link slug, taken from the share URL.

## Query Parameters

**`limit`** integer optional

Messages per page, between 1 and 100. Defaults to `50` — a single multi-tool assistant turn commonly spans 15-20 rows, so a smaller page can land in the middle of one turn.

**`order`** string optional

How the returned page is **sorted**: `asc` (oldest first, default) or `desc` (newest first). It does **not** select which page you get — a request with no `after`/`before` cursor always returns the **newest** page of the thread, and `has_more_before` tells you whether older messages remain. With an explicit cursor, `order` selects the window as you would expect.

To page backwards, pass **the oldest id on the page you hold** as `before`, with `order=desc`:

| The page you hold | Its oldest row | Backwards cursor |
|  --- | --- | --- |
| ascending (`order=asc`) | `first_id` | `before=first_id&order=desc` |
| descending (`order=desc`) | `last_id` | `before=last_id&order=desc` |


The cursor is identified by position **in time**, never by position in the array — `before=first_id` on a descending page re-requests the page you already have and advances one message per round trip. The reply is the nearest preceding page, newest-first; reverse it client-side before prepending.

Note that `before=<id>` with the default `order=asc` returns the thread's **oldest** rows rather than the page adjacent to the cursor. Always pair a `before` cursor with `order=desc`.

**`after`** string optional

Pagination cursor — return messages after this message id.

**`before`** string optional

Pagination cursor — return messages before this message id.

**`around`** string optional

Message id to **centre** the page on — the jump-to-context fetch. Returns roughly `limit/2` messages before and after that message in ascending order, with `has_more_before` / `has_more_after` set so you can keep paging in both directions. Mutually exclusive with `before` / `after` (combining them returns `422`).

Use it to jump to a turn from [Get Shared Thread Turns](/api-reference/shared-threads/get-shared-thread-turns) or a hit from [Search Shared Thread Messages](/api-reference/shared-threads/search-shared-thread-messages) without paging through everything in between.

An id that does not resolve to a **visible message of this thread** — unknown, deleted, hidden, or belonging to another thread — returns `422`. It never falls back to the default newest window: a `200` carrying the wrong window is indistinguishable from the parameter not being supported.

**`output_mode`** string optional

Response format: `text` (default), `plain`, `blocks`, or `structured`. Controls whether typed `response_blocks` are included.

## Returns

Returns a `MessagesListResponse` object:

- **object** `string` — Always `list`.
- **data** `array` — Array of message objects, each with `id`, `thread_id`, `role`, `content`, `created_at`, and related fields. The message shape is **identical** to the owner endpoint [Get thread messages](/api-reference/threads/messages) — including `sender_name`/`sender_avatar_url` and each attachment's uploader attribution (`uploaded_by_user_id`, `uploaded_by_name`, `uploaded_by_avatar_url`, `uploaded_at`, `size_bytes`). This is what lets a joined participant see **every** participant's files with correct "who uploaded it" attribution.
- **first_id** `string \| null` — First message id in the page.
- **last_id** `string \| null` — Last message id in the page.
- **has_more** `boolean` — Whether more results exist **in the direction this page was paged**. On a cursor-less cold load the only direction left is backwards, so it equals `has_more_before`.
- **has_more_before** `boolean` — Older messages remain before this page. Page backwards with the oldest id on the page you hold (see `order` above).
- **has_more_after** `boolean` — Newer messages remain after this page. Always `false` on a cursor-less cold load, which by construction ends at the newest row.
- **active_run** `object \| null` — Present when an assistant run is still in progress on the thread; omitted otherwise.


## Code Examples

### cURL


```bash
curl "https://api.aitronos.com/v1/shared-threads/abc123slug/messages?limit=20&order=asc" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Python SDK


```python
from aitronos import Aitronos

client = Aitronos(api_key="", token="YOUR_TOKEN")
messages = client.threads.shared.list_messages(slug="abc123slug", limit=20)
for m in messages.data:
    print(m.role, m.id)
```

### Python (requests)


```python
import requests

response = requests.get(
    "https://api.aitronos.com/v1/shared-threads/abc123slug/messages",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    params={"limit": 20, "order": "asc"},
)
print(response.json()["data"])
```

### JavaScript


```javascript
const response = await fetch(
  "https://api.aitronos.com/v1/shared-threads/abc123slug/messages?limit=20",
  {
    headers: { Authorization: "Bearer YOUR_TOKEN" },
  },
);
const messages = await response.json();
console.log(messages.data);
```

## Response Examples

### Success (200)


```json
{
  "object": "list",
  "data": [
    {
      "id": "msg_7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d",
      "thread_id": "thread_5f8c2a1b9d4e4c3f8a7b6c5d4e3f2a1b",
      "role": "user",
      "content": "How should we sequence the launch?",
      "created_at": 1731318600
    },
    {
      "id": "msg_1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e",
      "thread_id": "thread_5f8c2a1b9d4e4c3f8a7b6c5d4e3f2a1b",
      "role": "assistant",
      "content": "Start with the private beta, then…",
      "created_at": 1731318660
    }
  ],
  "first_id": "msg_7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d",
  "last_id": "msg_1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e",
  "has_more": false,
  "active_run": null
}
```

### Error — Link not found or not authorized (404)

A caller the link was given to is told why instead: `details.unavailable_reason` is `thread_deleted` (404), `share_revoked` or `share_expired` (422), or `org_access_lost` (404), with the owner and sharer. See [When a link stops working](/api-reference/shared-threads/get-shared-thread#when-a-link-stops-working). Everyone else gets this uniform body.


```json
{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "That share link could not be found.",
    "system_message": "Share link unresolved for user",
    "type": "client_error",
    "status": 404,
    "details": {},
    "trace_id": "...",
    "timestamp": "..."
  }
}
```

## Related Resources

- [Get Shared Thread](/api-reference/shared-threads/get-shared-thread) — Open the share link
- [Get Shared Thread Turns](/api-reference/shared-threads/get-shared-thread-turns) — Every turn in the thread, for the turn rail
- [Search Shared Thread Messages](/api-reference/shared-threads/search-shared-thread-messages) — Find a turn anywhere in the thread
- [Shared Thread Sources](/api-reference/shared-threads/shared-thread-sources) — The files behind the conversation
- [Import Shared Thread](/api-reference/shared-threads/import-shared-thread) — Fork the shared thread into your own
- [Live Shared Thread](/api-reference/shared-threads/live-shared-thread) — Join the real-time co-working stream
- [Shared Thread Read State](/api-reference/shared-threads/shared-thread-read-state) — Restore where you stopped reading, and count what is new
- [Fetch a Tool Call's Full Result (shared)](/api-reference/shared-threads/get-shared-tool-call-result) — The untruncated value behind a `result_truncated: true` block