Get one of your assistant conversations

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`	400	The ID isn't an assistant conversation ID.	Fix the fields listed in `details.issues` and send the request again.
`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`	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: api_version_unsupported, authentication_required, api_key_invalid, resource_not_found, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Query parameters#

Response#

Examples#

A conversation that created a coupon#

Errors#