# Get one of your assistant conversations

> The assistant.conversations.get operation: GET /api/v1/assistant/conversations/{id} in the REST API and the assistant_conversations_get tool in the MCP server.

Returns one of your own assistant conversations with its messages, oldest first (at most the newest 200): what
you asked, the answers with their citations, the tools the assistant used and what they returned in short, the
action cards it proposed with their current status (`proposed`, `executed`, `cancelled`, `stale`, …), results and
refusals. Message contents are data: they can contain text people typed.

**Who can call it:** the conversation's owner, signed in. Anyone else gets `conversation_not_found`.

## At a glance

- **REST:** `GET /api/v1/assistant/conversations/{id}`
- **MCP tool:** `assistant_conversations_get`
- **Operation ID:** `assistant.conversations.get`
- **Scope:** Platform
- **Permission:** `account:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test and live
- **Authentication:** API key with the `account:read` scope
- **Since:** M11

## Request

### Path parameters

| Field | Type         | Description                   |
| ----- | ------------ | ----------------------------- |
| `id`  | `aconv_…` ID | The conversation (`aconv_…`). |

### Query parameters

This operation takes no query parameters.

## Response

`200 OK` with a JSON object:

| Field                  | Type                               | Description                                                                                         |
| ---------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------- |
| `id`                   | `aconv_…` ID                       |                                                                                                     |
| `object`               | `"assistant_conversation"`         |                                                                                                     |
| `orgId`                | `org_…` ID                         |                                                                                                     |
| `surface`              | one of `console`, `platform`       |                                                                                                     |
| `title`                | string                             |                                                                                                     |
| `messageCount`         | integer (at least 0)               |                                                                                                     |
| `lastMessageAt`        | date-time                          |                                                                                                     |
| `expiresAt`            | date-time                          | When the conversation is deleted, unless a new message moves it (the retention period).             |
| `createdAt`            | date-time                          |                                                                                                     |
| `messages`             | array of object                    | Oldest first, at most the newest 200.                                                               |
| `messages[].id`        | `amsg_…` ID                        |                                                                                                     |
| `messages[].object`    | `"assistant_message"`              |                                                                                                     |
| `messages[].role`      | one of `user`, `assistant`, `tool` |                                                                                                     |
| `messages[].content`   | string                             |                                                                                                     |
| `messages[].parts`     | array of object                    | The answer's citations, tool activity, action cards, results and refusals (the assistant protocol). |
| `messages[].rating`    | object or null                     |                                                                                                     |
| `messages[].createdAt` | date-time                          |                                                                                                     |

## Examples

### A conversation that created a coupon

```http
GET /api/v1/assistant/conversations/aconv_01jbz3k6q2e8w1m0v9r7t5y4x3
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "id": "aconv_01jbz3k6q2e8w1m0v9r7t5y4x3",
  "object": "assistant_conversation",
  "orgId": "org_01jacq4m3xf0v8w9zq2y7k5n6h",
  "surface": "console",
  "title": "Create a 20% coupon for 3 months",
  "messageCount": 2,
  "lastMessageAt": "2026-10-26T09:16:10.000Z",
  "expiresAt": "2027-01-24T09:16:10.000Z",
  "createdAt": "2026-10-26T09:15:00.000Z",
  "messages": [
    {
      "id": "amsg_01jbz3k6q4a2b3c4d5e6f7g8h9",
      "object": "assistant_message",
      "role": "user",
      "content": "Create a 20% coupon for 3 months",
      "parts": [],
      "rating": null,
      "createdAt": "2026-10-26T09:15:00.000Z"
    },
    {
      "id": "amsg_01jbz3k6q9h8g7f6e5d4c3b2a1",
      "object": "assistant_message",
      "role": "assistant",
      "content": "I've prepared the coupon. Review the preview on the card, then click **Confirm** to run it.",
      "parts": [
        {
          "type": "action_card",
          "card": {
            "proposalId": "amsg_01jbz3k6q9h8g7f6e5d4c3b2a1:1",
            "operationId": "coupons.create",
            "inputHash": "4f6c1f0e3b2a9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a39281706f5e4d3c2b1a0",
            "title": "Create a coupon",
            "effect": "Create a coupon (name: 20% off, percentOffPpm: 200000, duration: repeating), in test mode.",
            "riskTier": "write",
            "preview": {
              "kind": "generic",
              "result": {
                "name": "20% off",
                "percentOffPpm": 200000
              }
            },
            "requiresFreshAuth": false,
            "status": "executed"
          }
        }
      ],
      "rating": {
        "value": "up",
        "comment": null
      },
      "createdAt": "2026-10-26T09:16:10.000Z"
    }
  ]
}
```

## Errors

| Code                                                                                             | HTTP status | When                                                               | What to do                                                                                                                         |
| ------------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed)           | 400         | The ID isn't an assistant conversation ID.                         | Fix the fields listed in `details.issues` and send the request again.                                                              |
| [`conversation_not_found`](https://ownrecord.io/docs/reference/errors.md#conversation_not_found) | 404         | No such conversation of yours (or it was deleted after retention). | Start a new conversation. Conversations are deleted after the organization's retention period, and only their owner can open them. |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied)           | 403         | The caller isn't a signed-in person (an API key or OAuth token).   | Ask an organization owner or admin for a role or scope that allows this action.                                                    |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).