> ## Documentation Index > Fetch the complete documentation index at: https://docs.support.onclarity.com/llms.txt > Use this file to discover all available pages before exploring further. # 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`. ## OpenAPI ````yaml /api-reference/voice-openapi.json get /v1/projects/{projectId}/conversations openapi: 3.0.3 info: title: Clarity Voice API version: '1.0' description: Voice agents, outbound calls, conversations, campaigns, and evals. servers: - url: https://voice-api.onclarity.com security: - organizationApiKey: [] tags: - name: Projects description: >- The projects your organization owns. Every other resource lives in a project. - name: Agents description: Create, configure, version and publish voice agents. - name: Outbound calls description: Have a published agent phone a number now. - name: Conversations description: >- One record per call session, with its calls, recordings, transcripts and artifacts. - name: Calls description: The calls of a project, with their status, direction, timing and outcome. - name: Campaigns description: Outbound calling campaigns that phone a list of numbers on a schedule. - name: Eval suites description: >- Reusable sets of eval scenarios and test cases to measure an agent against. - name: Eval judges description: The LLM judges that score eval calls against your test cases. - name: Eval scenarios description: The simulated-caller scenarios of your eval suites. - name: Eval test cases description: The checks a judge applies to each eval call. - name: Eval submissions description: Run an eval suite against an agent and read the verdicts. paths: /v1/projects/{projectId}/conversations: parameters: - $ref: '#/components/parameters/ProjectIdPath' get: tags: - Conversations summary: List conversations description: >- 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`. operationId: listConversations parameters: - name: direction in: query required: false schema: type: string enum: - incoming - outgoing description: Only inbound (`incoming`) or outbound (`outgoing`) conversations. - name: agent in: query required: false schema: type: string description: Only conversations an agent with this id took part in. - name: status in: query required: false schema: type: string enum: - pending - active - ended description: >- Only conversations in this state. `pending` — created but nobody has connected yet; `active` — in progress; `ended` — finished. - name: connected in: query required: false schema: type: boolean description: >- `true` for conversations where the caller joined, `false` for conversations where they never did (those have no transcript). - name: phone in: query required: false schema: type: string description: >- Substring match on either phone number of any call in the conversation (your number or the caller's). - name: caller in: query required: false schema: type: string description: Substring match on the far-end (customer) phone number. - name: callee in: query required: false schema: type: string description: Substring match on your side's phone number. - name: call_type in: query required: false schema: type: string enum: - pstn - sip - webrtc - whatsapp description: Only conversations that include a call of this channel. - name: date_from in: query required: false schema: type: string format: date-time description: Only conversations created at or after this time (ISO 8601). - name: date_to in: query required: false schema: type: string format: date-time description: Only conversations created at or before this time (ISO 8601). - name: has_errors in: query required: false schema: type: boolean description: >- `true` returns only conversations in which the platform detected a fatal error (for example a provider or tool failure that broke the call). - name: has_warnings in: query required: false schema: type: boolean description: >- `true` returns only conversations that raised an in-call warning, `false` only conversations that raised none. Combines with `warning_category` and `warning_severity`. - name: warning_category in: query required: false style: form explode: true schema: type: array items: type: string enum: - tool_failure - caller_not_understood - abuse_attempt - provider_unavailable - negative_sentiment - escalation_risk description: >- Only conversations with a warning in one of these categories. Repeat the parameter or separate values with commas. - name: warning_severity in: query required: false schema: type: string enum: - warning - critical description: Minimum warning severity. `critical` matches critical warnings only. - name: has_findings in: query required: false schema: type: boolean description: >- `true` returns conversations with a fatal error OR an in-call warning. - name: is_eval in: query required: false schema: type: boolean description: >- Evaluation (test) calls. Omit to include them; `false` hides them, `true` returns only them. - name: include_abandoned in: query required: false schema: type: boolean description: >- `true` also returns conversations that were created but never connected. They are hidden by default. - name: sort_by in: query required: false schema: type: string enum: - created_at - duration - ended_at default: created_at description: Sort key. Unknown values fall back to `created_at`. - name: sort_dir in: query required: false schema: type: string enum: - asc - desc default: desc description: Sort direction. - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 description: >- Page size. Values outside 1–100 are clamped. Takes precedence over `limit`. - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 200 default: 20 description: >- Page size when `page_size` is not given. Values outside 1–200 are clamped. Defaults to 20. - name: offset in: query required: false schema: type: integer minimum: 0 default: 0 description: Number of matching conversations to skip. responses: '200': description: One page of conversations. content: application/json: schema: $ref: '#/components/schemas/ConversationsListResponse' example: 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 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 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: The project does not exist or the credential has no access to it. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Project not found components: parameters: ProjectIdPath: name: projectId in: path required: true schema: type: string description: Project id schemas: ConversationsListResponse: type: object required: - conversations properties: conversations: type: array items: $ref: '#/components/schemas/Conversation' total: type: integer description: Number of conversations matching the filters, across all pages. limit: type: integer description: The page size that was applied. offset: type: integer description: The offset that was applied. Error: type: object required: - error additionalProperties: true properties: error: type: string description: Error message code: type: string description: >- A stable machine-readable reason, present on the refusals a client may branch on. Among them: `PUBLISH_CAPABILITY_REQUIRED` (403, the credential may not change what is live), `AGENT_NOT_PUBLISHED` (409, the agent has no published version yet), `AGENT_TYPE_NOT_DISPATCHABLE` (422, a Voice Assist agent named where an agent must place or take a call; the body carries `agent_type` and `agent_id`), `NOT_APPLICABLE_TO_AGENT_TYPE` (422, a voice-only setting written on a Voice Assist agent), `AGENT_TYPE_BOUNDARY` (409), `AGENT_TYPE_NOT_SUPPORTED` (400), `VOICE_ASSISTANT_REQUIRED` (403, the organization is not licensed for Voice Assist), `ORGANIZATION_UNAVAILABLE` (503) and `REGION_PROFILE_CONFLICT` (503). Conversation: type: object description: >- One interaction with a caller, from start to end. It can span several calls and several agent sessions (`participants`). required: - id - project_id - participants properties: id: type: string project_id: type: string platform_id: type: string nullable: true status: type: string nullable: true description: >- `pending` (created, nobody connected yet), `active` (in progress) or `ended`. hangup_reason: type: string nullable: true connected: type: boolean nullable: true description: >- Whether the caller joined. A conversation the caller never joined has no transcript. direction: type: string nullable: true duration: type: integer format: int64 nullable: true description: Length in seconds. initial_call_id: type: string nullable: true initial_agent_id: type: string nullable: true description: The agent that took the conversation first. agent_version_id: type: string nullable: true description: The agent version that served the conversation. participant_count: type: integer nullable: true allow_recording: type: boolean nullable: true conversation_summary: type: string nullable: true origin: type: string description: >- How the conversation started: `production` (real traffic), `try_it` (a test call from the web app), `demo` (the agent's public demo page) or `eval` (an evaluation run). enum: - production - try_it - demo - eval default: production csat_score: type: integer description: Customer satisfaction rating 1-5; null until rated. minimum: 1 maximum: 5 nullable: true csat_source: type: string description: >- Where the rating came from (e.g. try_it_ui, demo_ui, end_call_with_csat). nullable: true transcription_id: type: string nullable: true recording_id: type: string nullable: true pii_redaction: type: object nullable: true description: >- The organization's personal-data redaction setting as it was when the call started. Null on calls recorded before redaction existed. `source`: `fresh` / `stale` (read at call start, the second from cache), `unavailable` (could not be read; the call was not redacted), `no_org` (redaction not configurable for this project). properties: enabled: type: boolean entity_types: type: array items: type: string source: type: string enum: - fresh - stale - unavailable - no_org organization_id: type: integer nullable: true resolved_at: type: string pii_redaction_status: type: string nullable: true description: >- `pending` and `in_progress` mean redaction has not finished yet: the conversation's artifacts are withheld until it has. Null reads as `not_required`. enum: - not_required - pending - in_progress - applied summary_status: type: string nullable: true description: >- What happened to the conversation's summary: `pending` (still being written — for up to ten minutes after the call ended), `generated` (`conversation_summary` holds the text), `skipped` (nothing to summarize), `failed`, or `not_enabled` (the agent version has summaries off). Null on older calls. enum: - not_enabled - pending - generated - skipped - failed warnings: type: array description: >- In-call warnings raised on the conversation, most severe first. Filled by the list endpoint; always empty on the single-conversation read. items: $ref: '#/components/schemas/CallWarningSummary' campaign_id: type: string nullable: true description: The campaign that placed this call, if any. campaign_item_id: type: string nullable: true description: The campaign item (recipient) this call belongs to, if any. region_profile: type: string nullable: true description: >- The regional deployment profile that served the call; null for the default. call_language: type: string nullable: true description: >- For agents that speak two languages, the language most of the call was held in. Null for single-language agents and older calls. anecdote_back_link: type: object nullable: true additionalProperties: true description: >- Link to the conversation and ticket in the Clarity inbox once the call was imported. properties: conversation_id: type: integer ticket_id: type: integer synced_at: type: string participants: type: array items: $ref: '#/components/schemas/ConversationParticipant' created_at: type: string format: date-time nullable: true updated_at: type: string format: date-time nullable: true ended_at: type: string format: date-time nullable: true CallWarningSummary: type: object description: An in-call warning raised on a conversation, without its evidence. required: - id - category - severity - source - reason - occurrence_count - first_raised_at - last_updated_at properties: id: type: string category: type: string description: >- `tool_failure`, `caller_not_understood`, `abuse_attempt`, `provider_unavailable`, `negative_sentiment` or `escalation_risk`. severity: type: string enum: - warning - critical source: type: string enum: - deterministic - judgment description: >- `deterministic` (a rule fired) or `judgment` (a model judged the conversation). reason: type: string description: >- Why the warning was raised. A placeholder while personal-data redaction is still pending (`reason_withheld`). reason_withheld: type: boolean occurrence_count: type: integer first_raised_at: type: string last_updated_at: type: string raised_at_offset_ms: type: integer nullable: true description: >- Milliseconds from the start of the call, to find the moment in the recording. ConversationParticipant: oneOf: - $ref: '#/components/schemas/ConversationAgentParticipant' - $ref: '#/components/schemas/ConversationCallParticipant' discriminator: propertyName: type mapping: agent: '#/components/schemas/ConversationAgentParticipant' call: '#/components/schemas/ConversationCallParticipant' ConversationAgentParticipant: type: object description: | One agent session of the conversation whose agent still exists. A deleted agent's sessions are not listed here; the artifacts route (`SessionArtifacts`, `agent_id: null`) still serves them. required: - type - agent_id properties: type: type: string enum: - agent agent_id: type: string agent_metrics: additionalProperties: true nullable: true type: object session_id: type: string nullable: true joined_at: type: string format: date-time nullable: true left_at: type: string format: date-time nullable: true artifacts: $ref: '#/components/schemas/ConversationAgentArtifacts' nullable: true ConversationCallParticipant: type: object required: - type - call_id properties: type: type: string enum: - call call_id: type: string call_type: type: string enum: - pstn - sip - webrtc - whatsapp nullable: true participant_identity: type: string nullable: true direction: type: string enum: - incoming - outgoing nullable: true phone_number: type: string nullable: true did: type: string nullable: true remote_number: type: string nullable: true joined_at: type: string format: date-time nullable: true left_at: type: string format: date-time nullable: true hangup_reason: type: string nullable: true duration: type: integer format: int64 nullable: true is_eval: type: boolean description: >- Whether THIS CALL is a cloud-eval tester call. Derived from a column that submission deletion cannot clear, unlike eval_submission_id below. Per-call, and therefore narrower than the conversation's `origin`: it reads false once a retry unlinks the eval call from its conversation, where `origin` still reads `eval`. Badge the conversation off `origin`; use this to tell which participant of a conversation was the tester. eval_submission_id: type: string nullable: true description: >- Link to the cloud-eval submission this call belongs to. Null for real traffic AND for eval calls whose submission has since been deleted (that FK is ON DELETE SET NULL, so the call survives as a historical artifact with its pointer dropped). Do not use this to decide whether a call is an eval — use is_eval. ConversationAgentArtifacts: type: object description: > GCS location + persistence status of this agent-session's call artifacts. Populated by the runtime `artifacts-saved` callback fired by the voice agent after the call's recording is durably uploaded. required: - recording_url - timeline_url - metadata_url - status - saved_at properties: recording_url: type: string description: >- GCS URL of recording.wav (e.g. gs:///calls///recording.wav) timeline_url: type: string metadata_url: type: string status: type: string enum: - saved - partial - failed saved_at: type: string format: date-time responses: Unauthorized: description: No credential was sent, or the API key is invalid or revoked. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid or revoked token Forbidden: description: >- The credential carries no access to this project, or the operation needs administrative rights content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: organizationApiKey: type: http scheme: bearer description: >- Your organization API key (it starts with `anek_org_`). The same key works on the Voice API and the Support API. See [Authentication](/authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.