Conversations

Conversations save (persist) chat history for you. Every completion request that carries messages is stored, so you can fetch the full exchange later, including questions, answers, tool calls, and metadata. For example, a customer support agent can reopen a user’s troubleshooting session from yesterday and continue with the full context of what was already tried and discussed.

How conversations work

Persistence is automatic. You don’t need to send identifiers: Agent Studio generates a conversation ID and message IDs when you omit them, and returns the conversation ID in the X-Conversation-Id response header. Supplying your own IDs is optional and lets you set the storage key upfront so you can reference it without reading the header. Agent Studio automatically:

Saves every completion request that includes messages, even when you don’t supply IDs
Returns the stored conversation ID in the X-Conversation-Id response header
Generates conversation titles from the first user message (60-character maximum)
Respects your app’s retention policies (0, 30, 60, or 90 days)
Supports two access modes: unauthenticated (requires an API key with the logs ACL) and authenticated (user-scoped with a secure JWT).

Control the conversation ID

To set the storage key yourself, include a conversation ID and message IDs in your completion request:

curl -X POST "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/completions" \
  -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "alg_cnv_abc123",
    "messages": [
      {
        "id": "alg_msg_xyz789",
        "role": "user",
        "content": "How do I reset my password?"
      }
    ]
  }'

Both properties are optional:

id: the conversation identifier (prefix with alg_cnv_ for consistency)
messages[].id: unique identifier for each message (prefix with alg_msg_)

If you omit either property, Agent Studio generates it and returns the conversation ID in the X-Conversation-Id response header.

Unauthenticated conversations

Unauthenticated conversations provide basic persistence without user authentication. Conversations are not associated with any user—they exist as standalone entities accessible by conversation ID. This approach works well for testing, internal admin tools, and single-tenant applications without user accounts.

When to use

Applications without backend authentication infrastructure: when your application doesn’t have a backend to generate secure user tokens
Single-tenant apps: all users share the same data and user isolation isn’t required
Internal admin tools: where all users have full access to all conversations
Development and testing: for quick iteration without authentication setup
Prototypes and demos: for proof-of-concept implementations

How authenticated scoping works

Include the conversation and message IDs in your request. No additional authentication is needed:

curl -X POST "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/completions" \
  -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_SEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "alg_cnv_support_12345",
    "messages": [
      {
        "id": "alg_msg_001",
        "role": "user",
        "content": "My order hasn't arrived yet"
      }
    ]
  }'

To retrieve conversations, your API key needs the logs ACL:

curl -X GET "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/conversations" \
  -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_API_KEY"

curl -X GET "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/conversations/alg_cnv_support_12345" \
  -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_API_KEY"

Limitations

No user-specific retrieval: can’t retrieve conversations for a specific user. You get all conversations for the agent or none.
Requires admin ACL: the logs ACL is needed for retrieval (admin-level access)
Not suitable for multi-tenant apps: can’t isolate conversations by user
Not recommended for multi-user apps: use authenticated conversations when you need to manage conversations per user

Security limitations

Unauthenticated conversations have no user association. The backend doesn’t track which user created a conversation or link conversations to user identities. The only way to associate a conversation with a user is with the X-Algolia-Secure-User-Token header.

Conversations aren’t tied to any user.Anyone with a conversation ID and proper API key can access it.For multi-tenant SaaS apps, use authenticated conversations to enforce user-scoped data isolation.

Authenticated conversations with secure user tokens

Authenticated conversations link conversations to specific users, enabling user-scoped retrieval and management. This is the recommended approach for production apps.

Benefits

User association: conversations are linked to authenticated users from the JWT
User-specific retrieval: users can retrieve only their own conversations. They’re automatically filtered by user identity
Multi-user support: enable personalized conversation history for each user in your application
Memory integration: same user tokens work for both conversations and memory features
Production-ready: a secure, scalable approach for multi-user apps

How to set up

Authenticated conversations require secure user tokens to link conversations to specific users. For more information, see User authentication.

Send authenticated requests

Once you have set up user authentication, include the X-Algolia-Secure-User-Token header in your completion requests:

# Send message with user authentication
curl -X POST "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/completions" \
  -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_SEARCH_API_KEY" \
  -H "X-Algolia-Secure-User-Token: $SECURE_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "alg_cnv_user_chat_001",
    "messages": [
      {
        "id": "alg_msg_user_001",
        "role": "user",
        "content": "Show me my recent orders"
      }
    ]
  }'

Retrieve user’s conversations

With a secure user token, users can retrieve only their own conversations (requires search ACL):

curl -X GET "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/conversations" \
  -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_SEARCH_API_KEY" \
  -H "X-Algolia-Secure-User-Token: $SECURE_JWT_TOKEN"

curl -X GET "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/conversations/alg_cnv_user_chat_001" \
  -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_SEARCH_API_KEY" \
  -H "X-Algolia-Secure-User-Token: $SECURE_JWT_TOKEN"

How user filtering works

When you provide the X-Algolia-Secure-User-Token header:

Token validation: Agent Studio validates the JWT signature using your secret key (HS256 algorithm)
User extraction: the user identifier is extracted from the token’s sub (subject) claim
User association:
- For creation: the backend links the conversation to the authenticated user from the JWT
- For retrieval: queries automatically return only conversations linked to that user identity
Automatic scoping: all conversation operations are scoped to the authenticated user—enforced server-side based on the cryptographically signed token

Why this approach is secure:

User identity comes exclusively from the X-Algolia-Secure-User-Token header
There’s no way to provide a user identifier in the request body or query parameters
User identity can’t be manipulated by clients. It must come from a cryptographically signed JWT that only your backend can generate

ACL requirements by mode

Mode	API key ACL	User association	Retrieval scope
Authenticated	`search`	Linked to users	User-specific: retrieve by user identity
Unauthenticated	`logs`	No association	All-or-nothing: all conversations for the agent

Use authenticated mode with the search ACL for production environments. This enables user-specific conversation retrieval and avoids exposing admin-level API keys.

Retrieve conversation history

Agent Studio provides several endpoints to retrieve and manage conversation history.

List conversations

Retrieve a paginated list of conversations with optional date filtering:

curl -X GET "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/conversations?page=1&limit=20&startDate=2024-01-01&endDate=2024-12-31" \
  -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_SEARCH_API_KEY"

Response structure

JSON

{
  "data": [
    {
      "id": "alg_cnv_abc123",
      "agentId": "b3f1c2d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "title": "How do I reset my password?",
      "createdAt": "2024-11-20T10:30:00Z",
      "updatedAt": "2024-11-20T10:35:00Z",
      "lastActivityAt": "2024-11-20T10:35:00Z",
      "userToken": "user_123",
      "isFromDashboard": false,
      "messageCount": 8,
      "totalInputTokens": 950,
      "totalOutputTokens": 300,
      "totalTokens": 1250,
      "conversationMetadata": null,
      "feedback": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalCount": 95,
    "totalPages": 5
  }
}

Get single conversation

Retrieve a complete conversation including all messages:

curl -X GET "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/conversations/$CONVERSATION_ID" \
  -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_SEARCH_API_KEY"

Response includes:

Conversation metadata (title, timestamps, token counts)
All messages with roles, content, and tool calls
Message IDs and timestamps
Token usage per message

Manage retention and exports

Control retention and manage conversations in bulk with filtering, export, and deletion.

Retention policies

Conversations respect your app’s retention settings:

0 days: conversations are not persisted (ephemeral mode)
30 days: conversations are deleted after 30 days
60 days: conversations are deleted after 60 days
90 days: maximum retention period

When retention is 0, conversations are processed normally but not saved to the database. This is useful for apps that need real-time processing without persistence.

Agent Studio deletes conversations after the retention period expires. Export important conversations before they expire if you need long-term storage.

Filtering and export

Filter conversations by date range and export in bulk:

curl -X GET "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/conversations/export?startDate=2024-01-01&endDate=2024-12-31" \
  -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_API_KEY" \
  -o conversations_export.json

Bulk delete conversations matching filters:

curl -X DELETE "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/conversations?startDate=2024-01-01&endDate=2024-01-31" \
  -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_API_KEY"

Auto-generated titles

Agent Studio automatically generates conversation titles from the first user message:

Maximum length: 60 characters
Generation timing: titles are generated after the first user message.
Fallback: if generation fails, the conversation ID is used as the title

You don’t need to provide titles manually: they’re created automatically to help users identify conversations in lists.

Integration with memory

Secure user tokens enable both conversations and memory features:

Same authentication: one token works for both features
User isolation: both conversations and memories are scoped to the authenticated user
Unified experience: users get personalized agents with both conversation history and memory

When you set up secure user tokens for memory, conversation authentication works automatically.

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

How conversations work

Control the conversation ID

Unauthenticated conversations

When to use

How authenticated scoping works

Limitations

Security limitations

Authenticated conversations with secure user tokens

Benefits

How to set up

Send authenticated requests

Retrieve user’s conversations

How user filtering works

ACL requirements by mode

Retrieve conversation history

List conversations

Response structure

Get single conversation

Manage retention and exports

Retention policies

Filtering and export

Auto-generated titles

Integration with memory

See also

​How conversations work

​Control the conversation ID

​Unauthenticated conversations

​When to use

​How authenticated scoping works

​Limitations

​Security limitations

​Authenticated conversations with secure user tokens

​Benefits

​How to set up

​Send authenticated requests

​Retrieve user’s conversations

​How user filtering works

​ACL requirements by mode

​Retrieve conversation history

​List conversations

​Response structure

​Get single conversation

​Manage retention and exports

​Retention policies

​Filtering and export

​Auto-generated titles

​Integration with memory

​See also

How conversations work

Control the conversation ID

Unauthenticated conversations

When to use

How authenticated scoping works

Limitations

Security limitations

Authenticated conversations with secure user tokens

Benefits

How to set up

Send authenticated requests

Retrieve user’s conversations

How user filtering works

ACL requirements by mode

Retrieve conversation history

List conversations

Response structure

Get single conversation

Manage retention and exports

Retention policies

Filtering and export

Auto-generated titles

Integration with memory

See also