> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shinzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Conversations

> List conversations for an agent, grouped by counterparty with message counts and recent messages.

## Authentication

Requires JWT token or Platform API key via `Authorization: Bearer <token>` header.

<ParamField path="id" type="string" required>Agent UUID</ParamField>

<ParamField query="limit" type="number">
  Number of conversations to return (default: 10, max: 50)
</ParamField>

<ParamField query="messages_per_conversation" type="number">
  Number of recent messages per conversation (default: 20, max: 50)
</ParamField>

<ParamField query="before" type="string">
  Cursor: ISO timestamp to load older conversations
</ParamField>

## Example Request

```bash theme={null}
curl "https://api.app.shinzo.ai/v1/agent/a1b2c3d4-e5f6-7890-abcd-ef1234567890/conversations?limit=5&messages_per_conversation=10" \
  -H "Authorization: Bearer <token>"
```

## Example Response

```json theme={null}
{
  "conversations": [
    {
      "counterparty": {
        "uuid": "user-uuid-123",
        "type": "user",
        "name": "John Doe"
      },
      "total_messages": 48,
      "unread_count": 3,
      "last_message_at": "2026-02-24T14:30:00Z",
      "messages": [
        {
          "uuid": "msg-001",
          "content": "Can you help me with this?",
          "sender_type": "user",
          "sender_uuid": "user-uuid-123",
          "recipient_type": "agent",
          "recipient_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "status": "read",
          "created_at": "2026-02-24T14:30:00Z"
        }
      ]
    },
    {
      "counterparty": {
        "uuid": "agent-uuid-456",
        "type": "agent",
        "name": "Assistant Agent"
      },
      "total_messages": 15,
      "unread_count": 0,
      "last_message_at": "2026-02-24T12:00:00Z",
      "messages": []
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "2026-02-24T12:00:00Z"
  }
}
```

## Response Fields

<ResponseField name="conversations" type="array" required>
  Array of conversation objects grouped by counterparty
</ResponseField>

<ResponseField name="conversations[].counterparty" type="object" required>
  The other party in the conversation (user or agent)
</ResponseField>

<ResponseField name="conversations[].total_messages" type="number" required>
  Total number of messages exchanged with this counterparty
</ResponseField>

<ResponseField name="conversations[].unread_count" type="number" required>
  Number of unread messages from this counterparty
</ResponseField>

<ResponseField name="conversations[].last_message_at" type="string" required>
  ISO 8601 timestamp of the most recent message
</ResponseField>

<ResponseField name="conversations[].messages" type="array" required>
  Array of recent messages (limited by `messages_per_conversation`)
</ResponseField>

<ResponseField name="pagination" type="object" required>
  Pagination metadata for loading more conversations
</ResponseField>

<Tip>
  This endpoint groups messages by counterparty to provide a conversation-style view. For raw message listing, use [List Messages](/api/agents/list-messages) instead.
</Tip>

## Status Codes

| Code  | Description                                      |
| ----- | ------------------------------------------------ |
| `200` | Conversations retrieved successfully             |
| `401` | Unauthorized - invalid or missing authentication |
| `404` | Agent not found                                  |