List conversations

curl --request GET \
  --url https://voice-api.onclarity.com/v1/projects/{projectId}/conversations \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://voice-api.onclarity.com/v1/projects/{projectId}/conversations"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://voice-api.onclarity.com/v1/projects/{projectId}/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "conversations": [
    {
      "id": "8f14e45f-ceea-467f-a0e6-3f1c2b9d7a10",
      "project_id": "3c59dc04-8a4b-4f7e-9b1a-6c2a0e5d1f22",
      "platform_id": "RM_kQ3vZx7pLm2T",
      "status": "ended",
      "hangup_reason": "caller_hangup",
      "connected": true,
      "direction": "incoming",
      "duration": 184,
      "initial_call_id": "1b6453892473a467d07372d45eb05abc",
      "initial_agent_id": "6f4922f4-5568-461a-8f1d-9c3b2a1e7d55",
      "agent_version_id": "2e1c7a90-4b1d-4c3e-9f2a-7d8e6b5a4c33",
      "participant_count": 2,
      "allow_recording": true,
      "conversation_summary": "The caller asked to move their appointment to Thursday; the agent rebooked it.",
      "warnings": [],
      "transcription_id": null,
      "recording_id": null,
      "origin": "production",
      "csat_score": null,
      "csat_source": null,
      "campaign_id": null,
      "campaign_item_id": null,
      "pii_redaction": null,
      "pii_redaction_status": null,
      "region_profile": null,
      "summary_status": "generated",
      "call_language": null,
      "clock": {
        "time_zone": "Asia/Riyadh",
        "source": "caller_number",
        "at": "2026-10-20T09:15:01.512Z",
        "hijri": true
      },
      "participants": [
        {
          "type": "agent",
          "agent_id": "6f4922f4-5568-461a-8f1d-9c3b2a1e7d55",
          "agent_metrics": null,
          "session_id": "AJ_x8Kd2mQp4Vn",
          "joined_at": "2026-10-20T09:15:02.000Z",
          "left_at": "2026-10-20T09:18:06.000Z",
          "artifacts": null
        },
        {
          "type": "call",
          "call_id": "1b6453892473a467d07372d45eb05abc",
          "call_type": "pstn",
          "participant_identity": "sip_+966500000000",
          "direction": "incoming",
          "phone_number": "+966500000000",
          "did": "+966110000000",
          "remote_number": "+966500000000",
          "joined_at": "2026-10-20T09:15:01.000Z",
          "left_at": "2026-10-20T09:18:05.000Z",
          "hangup_reason": "caller_hangup",
          "duration": 184,
          "is_eval": false,
          "eval_submission_id": null
        }
      ],
      "anecdote_back_link": null,
      "created_at": "2026-10-20T09:15:00.000Z",
      "updated_at": "2026-10-20T09:18:07.000Z",
      "ended_at": "2026-10-20T09:18:06.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

{
  "error": "Invalid or revoked token"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "Project not found"
}

Conversations

List conversations

Lists the project’s conversations, newest first by default. A conversation is one interaction with a caller from start to end; it can span several calls (for example after a transfer) and several agent sessions. Use the filters to narrow the list and page_size + offset to page through it; total is the number of matching conversations across all pages.

Sessions that were started but never connected (nobody joined) are left out unless you pass include_abandoned=true.

GET

projects

{projectId}

conversations

List conversations

curl --request GET \
  --url https://voice-api.onclarity.com/v1/projects/{projectId}/conversations \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://voice-api.onclarity.com/v1/projects/{projectId}/conversations"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://voice-api.onclarity.com/v1/projects/{projectId}/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "conversations": [
    {
      "id": "8f14e45f-ceea-467f-a0e6-3f1c2b9d7a10",
      "project_id": "3c59dc04-8a4b-4f7e-9b1a-6c2a0e5d1f22",
      "platform_id": "RM_kQ3vZx7pLm2T",
      "status": "ended",
      "hangup_reason": "caller_hangup",
      "connected": true,
      "direction": "incoming",
      "duration": 184,
      "initial_call_id": "1b6453892473a467d07372d45eb05abc",
      "initial_agent_id": "6f4922f4-5568-461a-8f1d-9c3b2a1e7d55",
      "agent_version_id": "2e1c7a90-4b1d-4c3e-9f2a-7d8e6b5a4c33",
      "participant_count": 2,
      "allow_recording": true,
      "conversation_summary": "The caller asked to move their appointment to Thursday; the agent rebooked it.",
      "warnings": [],
      "transcription_id": null,
      "recording_id": null,
      "origin": "production",
      "csat_score": null,
      "csat_source": null,
      "campaign_id": null,
      "campaign_item_id": null,
      "pii_redaction": null,
      "pii_redaction_status": null,
      "region_profile": null,
      "summary_status": "generated",
      "call_language": null,
      "clock": {
        "time_zone": "Asia/Riyadh",
        "source": "caller_number",
        "at": "2026-10-20T09:15:01.512Z",
        "hijri": true
      },
      "participants": [
        {
          "type": "agent",
          "agent_id": "6f4922f4-5568-461a-8f1d-9c3b2a1e7d55",
          "agent_metrics": null,
          "session_id": "AJ_x8Kd2mQp4Vn",
          "joined_at": "2026-10-20T09:15:02.000Z",
          "left_at": "2026-10-20T09:18:06.000Z",
          "artifacts": null
        },
        {
          "type": "call",
          "call_id": "1b6453892473a467d07372d45eb05abc",
          "call_type": "pstn",
          "participant_identity": "sip_+966500000000",
          "direction": "incoming",
          "phone_number": "+966500000000",
          "did": "+966110000000",
          "remote_number": "+966500000000",
          "joined_at": "2026-10-20T09:15:01.000Z",
          "left_at": "2026-10-20T09:18:05.000Z",
          "hangup_reason": "caller_hangup",
          "duration": 184,
          "is_eval": false,
          "eval_submission_id": null
        }
      ],
      "anecdote_back_link": null,
      "created_at": "2026-10-20T09:15:00.000Z",
      "updated_at": "2026-10-20T09:18:07.000Z",
      "ended_at": "2026-10-20T09:18:06.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

{
  "error": "Invalid or revoked token"
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "Project not found"
}

Authorizations

Authorization

string

header

required

Your organization API key (it starts with anek_org_). The same key works on the Voice API and the Support API. See Authentication.

Path Parameters

projectId

string

required

Project id

Query Parameters

direction

enum<string>

Only inbound (incoming) or outbound (outgoing) conversations.

Available options:

incoming,

outgoing

agent

string

Only conversations an agent with this id took part in.

status

enum<string>

Only conversations in this state. pending — created but nobody has connected yet; active — in progress; ended — finished.

Available options:

pending,

active,

ended

connected

boolean

true for conversations where the caller joined, false for conversations where they never did (those have no transcript).

phone

string

Substring match on either phone number of any call in the conversation (your number or the caller's).

caller

string

Substring match on the far-end (customer) phone number.

callee

string

Substring match on your side's phone number.

call_type

enum<string>

Only conversations that include a call of this channel.

Available options:

pstn,

sip,

webrtc,

whatsapp

date_from

string<date-time>

Only conversations created at or after this time (ISO 8601).

date_to

string<date-time>

Only conversations created at or before this time (ISO 8601).

has_errors

boolean

true returns only conversations in which the platform detected a fatal error (for example a provider or tool failure that broke the call).

has_warnings

boolean

true returns only conversations that raised an in-call warning, false only conversations that raised none. Combines with warning_category and warning_severity.

warning_category

enum<string>[]

Only conversations with a warning in one of these categories. Repeat the parameter or separate values with commas.

Available options:

tool_failure,

caller_not_understood,

abuse_attempt,

provider_unavailable,

negative_sentiment,

escalation_risk

warning_severity

enum<string>

Minimum warning severity. critical matches critical warnings only.

Available options:

warning,

critical

has_findings

boolean

true returns conversations with a fatal error OR an in-call warning.

is_eval

boolean

Evaluation (test) calls. Omit to include them; false hides them, true returns only them.

include_abandoned

boolean

true also returns conversations that were created but never connected. They are hidden by default.

sort_by

enum<string>

default:created_at

Sort key. Unknown values fall back to created_at.

Available options:

created_at,

duration,

ended_at

sort_dir

enum<string>

default:desc

Sort direction.

Available options:

asc,

desc

page_size

integer

Page size. Values outside 1–100 are clamped. Takes precedence over limit.

Required range: 1 <= x <= 100

limit

integer

default:20

Page size when page_size is not given. Values outside 1–200 are clamped. Defaults to 20.

Required range: 1 <= x <= 200

offset

integer

default:0

Number of matching conversations to skip.

Required range: x >= 0

Response

One page of conversations.

conversations

object[]

required

Show child attributes

total

integer

Number of conversations matching the filters, across all pages.

limit

integer

The page size that was applied.

offset

integer

The offset that was applied.