> ## 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. # Get a conversation > Returns one conversation with its participants (the agent sessions and the calls that took part), status, duration, summary and outcome fields. For the transcript, recording and per-turn detail, use Get conversation artifacts. `warnings` is always empty on this endpoint; the list endpoint fills it. ## OpenAPI ````yaml /api-reference/voice-openapi.json get /v1/projects/{projectId}/conversations/{id} 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/{id}: parameters: - $ref: '#/components/parameters/ProjectIdPath' - $ref: '#/components/parameters/ConversationId' get: tags: - Conversations summary: Get a conversation description: >- Returns one conversation with its participants (the agent sessions and the calls that took part), status, duration, summary and outcome fields. For the transcript, recording and per-turn detail, use Get conversation artifacts. `warnings` is always empty on this endpoint; the list endpoint fills it. operationId: getConversation responses: '200': description: The conversation. content: application/json: schema: $ref: '#/components/schemas/Conversation' example: 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: outgoing duration: 95 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: Reminder call; the customer confirmed the delivery window. warnings: [] transcription_id: null recording_id: null origin: production csat_score: null csat_source: null campaign_id: 0d6f1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b campaign_item_id: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d 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:16:37.000Z' artifacts: null anecdote_back_link: null created_at: '2026-10-20T09:15:00.000Z' updated_at: '2026-10-20T09:16:38.000Z' ended_at: '2026-10-20T09:16:37.000Z' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: >- The conversation, or the project, does not exist or is not accessible. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Conversation not found components: parameters: ProjectIdPath: name: projectId in: path required: true schema: type: string description: Project id ConversationId: name: id in: path required: true schema: type: string description: Conversation id schemas: 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 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). 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.