GET /v1/conversations, list and inspect conversations

Written by Aashiq, Founder, AskVault · Reviewed by Aashiq

Last updated: May 15, 2026 · 5 min read

TL;DR

Read conversations programmatically. List with filters by channel, status, tag, or date. Fetch full message history. Search by text or tag. Available on every paid plan with up to 50,000 conversations per month on Business and pagination up to 100 per page.

Endpoints

Four endpoints for reading conversations:

• GET /v1/conversations - list conversations with filters
• GET /v1/conversations/{conversation_id} - fetch a full conversation
• GET /v1/conversations/{conversation_id}/messages - fetch messages with pagination
• POST /v1/conversations/{conversation_id}/notes - add an internal note

All require Authorization: Bearer ak_xxx. See authentication.

List conversations

curl

curl https://api.askvault.co/v1/conversations?workspace_id=wt_xxx&status=open&limit=20 \
-H "Authorization: Bearer ak_xxx"

Python

import requests
r = requests.get(
  "https://api.askvault.co/v1/conversations",
  headers={"Authorization": "Bearer ak_xxx"},
  params={"workspace_id": "wt_xxx", "status": "open", "limit": 20},
)
print(r.json())

Node.js

const r = await fetch(
"https://api.askvault.co/v1/conversations?workspace_id=wt_xxx&status=open&limit=20",
{ headers: { "Authorization": "Bearer ak_xxx" } },
);
console.log(await r.json());

Response:

{
  "conversations": [
    {
      "id": "conv_xxx",
      "workspace_id": "wt_xxx",
      "channel": "widget",
      "status": "open",
      "started_at": "2026-05-15T13:42:00.000Z",
      "last_message_at": "2026-05-15T13:48:32.000Z",
      "message_count": 8,
      "customer": {
        "email": "verified@example.com",
        "name": "Jane Doe",
        "phone": null
      },
      "tags": ["billing", "urgent"],
      "sla_state": "in_compliance"
    }
  ],
  "pagination": {
    "next_cursor": "cur_xxx",
    "has_more": true
  }
}

List filters

Param	Type	Description
workspace_id	string	Required. The workspace to read from.
channel	string	Filter by widget, whatsapp, telegram, slack, discord, email, voice, sms, intercom, hosted, api.
status	string	Filter by open, claimed, escalated, snoozed, resolved, archived.
tag	string	Filter by tag. Repeat for multiple tags (AND match).
since	string	ISO 8601 timestamp. Only conversations started after this.
until	string	ISO 8601 timestamp. Only conversations started before this.
q	string	Full-text search across messages. Returns conversations with matching content.
email	string	Filter to one customer's conversations.
sla_state	string	in_compliance, at_risk, breached.
limit	integer	Page size. 1 to 100. Default 20.
cursor	string	Pagination cursor from previous response.

Fetch a single conversation

curl https://api.askvault.co/v1/conversations/conv_xxx \
  -H "Authorization: Bearer ak_xxx"

Returns the conversation with its full message history:

{
  "id": "conv_xxx",
  "workspace_id": "wt_xxx",
  "channel": "widget",
  "status": "resolved",
  "started_at": "2026-05-15T13:42:00.000Z",
  "resolved_at": "2026-05-15T13:55:21.000Z",
  "customer": { ... },
  "tags": ["billing"],
  "messages": [
    {
      "id": "msg_xxx",
      "role": "user",
      "content": "What's the status of my subscription?",
      "created_at": "2026-05-15T13:42:01.000Z"
    },
    {
      "id": "msg_yyy",
      "role": "assistant",
      "content": "Your subscription...",
      "sources": [...],
      "created_at": "2026-05-15T13:42:03.000Z",
      "tokens_used": 187
    }
  ],
  "internal_notes": [
    {
      "id": "note_xxx",
      "author": "agent@yourco.com",
      "content": "Verified plan tier. Escalating to billing.",
      "created_at": "2026-05-15T13:44:11.000Z"
    }
  ],
  "audit_log": [...]
}

Fetch messages with pagination

For long conversations (100+ messages), use the messages endpoint with pagination:

curl "https://api.askvault.co/v1/conversations/conv_xxx/messages?limit=50&cursor=cur_xxx" \
  -H "Authorization: Bearer ak_xxx"

Param	Type	Description
limit	integer	1 to 100. Default 50.
cursor	string	Pagination cursor.
order	string	asc (default) or desc.

Add an internal note

Internal notes are agent-only. Visitors don't see them.

curl -X POST https://api.askvault.co/v1/conversations/conv_xxx/notes \
  -H "Authorization: Bearer ak_xxx" \
  -H "Content-Type: application/json" \
  -d '{"content": "Verified plan tier. Escalating to billing."}'

Response:

{
  "id": "note_xxx",
  "conversation_id": "conv_xxx",
  "content": "Verified plan tier. Escalating to billing.",
  "author": "api_key:ak_xxx_name",
  "created_at": "2026-05-15T13:44:11.000Z"
}

The author is automatically set to your API key's display name. To override (e.g., to record which human agent acted via your custom UI), include author_email in the body.

Common patterns

Three patterns we see most often:

1. CRM sync. Pull conversations every 5 minutes since the last sync timestamp. Push to your CRM as activities. Use since filter and persist the latest timestamp seen.

2. Custom dashboard. List today's conversations with since={start_of_today}. Render in your internal admin UI for support managers. Combine with the analytics endpoints for aggregate metrics.

3. Customer-success outreach. Fetch resolved conversations tagged at_risk from the last 30 days. Build a list of customers who had bad experiences. Use for outreach.

Pagination

All list endpoints use cursor-based pagination. The response includes pagination.next_cursor. Pass it as cursor in the next request.

When has_more is false, you've reached the end. Don't paginate further; you'll just get empty results.

Limits

• Page size. Max 100 per page on list endpoints.
• Rate limits. Same as API rate limits for your plan.
• Date range. No hard cap, but queries spanning > 90 days are slower. Paginate in 30-day windows for best performance.

Common pitfalls

Pagination loops on has_more: true without progress. You're not passing the new next_cursor correctly. Confirm the cursor in your next request matches the one from the previous response.

Missing conversations. Filter is too tight. Remove filters one at a time to find what's excluding them.

Slow responses on big workspaces. Workspaces with 100k+ conversations should always filter by date. Unfiltered queries are deprecated for very large workspaces.

Customer email shows null. The conversation wasn't identity-verified or collect_lead didn't capture it. The conversation exists; the customer is anonymous.

FAQ

Can I update a conversation's status via API?

Yes. PATCH /v1/conversations/{id} with {"status": "resolved"}. Same endpoint accepts tags, priority, internal_notes.

Can I delete a conversation?

Yes. DELETE /v1/conversations/{id}. Cascades to messages and any attached notes. Audit log entries are retained.

How long are conversations retained?

365 days on standard plans. Extended to 6 years on Enterprise (HIPAA-relevant minimum). Auto-deleted at retention end.

Can I bulk-export?

Yes, but use the dashboard's bulk-export feature for very large pulls. The API is paginated and rate-limited; trying to export 100k conversations via the list endpoint will take a while.

Does this endpoint include messages from human agents?

Yes. Both AI-generated and human-agent messages appear in the messages array, distinguished by the role field (assistant for AI, agent for human).

Related guides

• Getting started with the AskVault API
• POST /v1/query reference
• Webhooks reference
• Live Chat inbox
• Rate limits per plan

Start building with the AskVault API

Generate an API key in the dashboard, then send your first request.

Get an API key → Read the API docs

Was this page helpful? Yes No