Conversation History

Retrieve and analyze historical conversation data for users and services.

Data Access Access conversation history for analytics, quality assurance, and user experience improvements.

List Conversations

Get conversations

get

Retrieve conversations in an organization based on supplied filters.

Permissions

This endpoint may be impacted by the following permissions:

• The final_message field in the response is only non-empty if the authenticated user has the Conversation.GetMessage permission on the final message.
• The version_set_info field in the response is only non-empty if the authenticated user has the Service.GetVersionSet permission on the version set.
• Only conversations for which the user has the Conversation.GetConversation permission are returned.

Authorizations

Bearer-Authorization & Bearer-Authorization-OrganizationAPI-Key-Authorization-Key & API-Key-Authorization-ID & API-Key-Authorization-UserID

Path parameters

organizationstringRequired

Query parameters

user_idstring[]Optional

The identifier of the user whose conversations to retrieve.

Default: []

service_idstring[]Optional

The identifier of the service whose conversation to retrieve.

Default: []

is_finishedany ofOptional

Whether the conversation is finished.

booleanOptional

or

nullOptional

idstring[]Optional

The ID of the conversation to retrieve.

Default: []

limitinteger · max: 150Optional

The maximum number of conversations to retrieve.

Default: 150

continuation_tokenintegerOptional

The continuation token returned from the previous response to retrieve the next set of conversations.

Default: 0

sort_bystring[]Optional

The field to sort the conversations by. Supported fields are created_at. Specify a + before the field name to indicate ascending sorting and - for descending sorting. Multiple fields can be specified to break ties.

Default: []

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

or

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

422

Invalid request path parameter or query parameter failed validation.

429

The user has exceeded the rate limit of 15 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

get

HTTPcURLJavaScriptPython

GET /v1/{organization}/conversation/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "conversations": [
    {
      "id": "text",
      "user_id": "text",
      "created_at": "2025-10-11T15:09:38.818Z",
      "is_finished": true,
      "is_analyzed": true,
      "completed_post_processings": [
        "generate-user-models"
      ],
      "final_message": "text",
      "service_id": "text",
      "version_set_info": {
        "name": "text",
        "agent_version_info": [],
        "service_hierarchical_state_machine_version_info": [],
        "llm_model_preferences": {
          "ANY_ADDITIONAL_PROPERTY": {
            "llm_name": "text",
            "top_p": 1,
            "temperature": 1,
            "top_k": 1
          }
        }
      },
      "num_messages": 1
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

cURL

curl --request GET \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/conversation/?user_id=<USER-ID>&limit=10&continuation_token=0' \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
     --header 'accept: application/json'

Python SDK

from amigo_sdk import AmigoClient
from amigo_sdk.models import GetConversationsParametersQuery

with AmigoClient() as client:
    conversations = client.conversation.get_conversations(
        GetConversationsParametersQuery(
            user_id=user_id,
            limit=10,
            continuation_token=0,
        )
    )

    for c in conversations.conversations or []:
        print(f"Conversation ID: {c.id}")

TypeScript SDK

import { AmigoClient } from "@amigo-ai/sdk";

const client = new AmigoClient({ /* config */ });
const conversations = await client.conversations.getConversations({
  user_id: userId,
  limit: 10,
  continuation_token: 0,
});

conversations.conversations?.forEach((c) => {
  console.log(`Conversation ID: ${c.id}`);
});

Query Parameters

Parameter	Type	Description
user_id	string	Filter by specific user
service_id	string	Filter by specific service
is_finished	boolean	Filter by conversation state
limit	integer	Results per page (max 100)
continuation_token	string	Pagination token

Get Conversation Messages

Retrieve all messages from a specific conversation.

Message Order Messages are returned in chronological order, preserving the conversation flow.

Get conversation messages

get

Retrieve messages in a conversation, sorted in the specified order, up to the specified limit.

Permissions

This endpoint is impacted by the following permissions:

• Only messages that the authenticated user has Conversation.GetMessage permission on will be returned.

Authorizations

Bearer-Authorization & Bearer-Authorization-OrganizationAPI-Key-Authorization-Key & API-Key-Authorization-ID & API-Key-Authorization-UserID

Path parameters

organizationstringRequired

conversation_idstringRequired

The identifier of the conversation.

Pattern: ^[a-f0-9]{24}$

Query parameters

idstring[]Optional

The IDs of the messages to retrieve.

Default: []

interaction_idstring[]Optional

The IDs of the interactions to retrieve messages for.

Default: []

limitinteger · max: 500Optional

The maximum number of messages to return. At most 500 messages can be returned in one request.

Default: 500

continuation_tokenintegerOptional

The continuation token to use to retrieve the next set of messages.

Default: 0

sort_bystring[]Optional

The field to sort the messages by. Supported fields are interaction_id and created_at. Specify a + before the field name to indicate ascending sorting and - for descending sorting. Multiple fields can be specified to break ties.

Default: []

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

or

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or conversation is not found.

422

Invalid request path parameter failed validation.

429

The user has exceeded the rate limit of 20 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

get

HTTPcURLJavaScriptPython

GET /v1/{organization}/conversation/{conversation_id}/messages/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "messages": [
    {
      "id": "text",
      "interaction_id": "text",
      "created_at": "2025-10-11T15:09:38.818Z",
      "sender": "text",
      "message": "text",
      "format": "text",
      "message_type": "user-message",
      "message_metadata": [
        "text"
      ]
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

cURL

curl --request GET \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/conversation/<CONVERSATION-ID>/messages/' \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
     --header 'accept: application/json'

Python SDK

from amigo_sdk import AmigoClient

with AmigoClient() as client:
    msgs = client.conversation.get_conversation_messages(conversation_id=conversation_id)
    for m in msgs.messages or []:
        print(f"Message from {m.sender}: {m.message_text}")

TypeScript SDK

const messages = await client.conversations.getConversationMessages(conversationId);
messages.messages?.forEach((m) => {
  console.log(`Message from ${m.sender}: ${m.message_text}`);
});