AigentlyDevelopers
All pages

API reference

List conversations

GET /v1/conversations

View as Markdown

Conversations this key can reach, newest first. Use order=changed with changed_after to sync: oldest change first, and the last page's next_cursor is the place to ask again from later. Changes from the last minute wait for the next page. With q, only conversations whose transcript has those words, each with the passage that matched — which also needs transcripts:read, 30 a minute per key. Needs conversations:read.

Parameters

Name In Type Required Description
order query Order No newest, oldest or changed.
agent_id query string (uuid) or null No
project_id query string (uuid) or null No
channel query Channel or null No
direction query Direction or null No
status query array of ConversationStatus or null No Repeat to ask for several.
disposition query Disposition or null No
outcome query Outcome or null No The analysis's outcome.
ended_by query EndedBy or null No
mode query ConversationMode or null No
phone_number_id query string (uuid) or null No
from_number query string or null No
to_number query string or null No
campaign_id query string (uuid) or null No
external_id query string or null No Your own id, as POST /v1/calls or /v1/chats sent it.
created_after query string (date-time) or null No Started at or after this time.
created_before query string (date-time) or null No Started before this time.
changed_after query string (date-time) or null No Changed at or after this time.
changed_before query string (date-time) or null No Changed before this time.
limit query integer No How many to return, 1 to 100.
q query string or null No Words that were said. A word also finds longer ones that start with it (refund finds refunded), a phrase in quotes is found as written, and -word leaves out the conversations that have it. Needs transcripts:read.
cursor query string or null No next_cursor from the previous page, with the same filters.

Answer

200 with ConversationList.

Errors

Every error is a problem document with a stable code.

Status When
401 The key is missing, mistyped, unknown, revoked or expired.
403 The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something.
422 Validation Error
429 Too many requests for this key or its organization; see Retry-After.
500 Something went wrong on our side. Quote the request_id to support.

Examples

List conversations
#!/bin/sh
# List conversations
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations?agent_id=8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c&status=completed&limit=10" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"
Sync what changed
#!/bin/sh
# Sync what changed. Send each page's next_cursor back as cursor= until has_more is false.
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations?order=changed&changed_after=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"
Find conversations by what was said
#!/bin/sh
# Find conversations by what was said. Each one comes with the passage that matched.
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations?q=refund&limit=10" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

Try it

Sends this request to the API from your browser, with a test key. Nothing it does rings a phone.