> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eigi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Conversation by ID

> Retrieve detailed information about a specific conversation using its unique ID

## Overview

This endpoint retrieves comprehensive details about a conversation, including status, transcript, analysis, and metadata. Use this to fetch conversation data after a call has been completed or while it's in progress.

## Authentication

<ParamField header="X-API-Key" type="string" required>
  Your eigi.ai API key. Must be prefixed with `vk_`.
</ParamField>

## Path Parameters

<ParamField path="conversation_id" type="string" required>
  The unique identifier (UUID format) of the conversation to retrieve.

  Example: `35d33a43-176c-405c-92bf-db972035df28`
</ParamField>

## Response

<ResponseField name="agent_id" type="string">
  ID of the agent that handled this conversation
</ResponseField>

<ResponseField name="conversation_id" type="string">
  Unique identifier (UUID) for the conversation
</ResponseField>

<ResponseField name="conversation_type" type="string">
  Type of conversation: `DAILY`, `TELEPHONY`, `WHATSAPP`, or `CHAT`
</ResponseField>

<ResponseField name="conversation_analysis" type="array | null">
  AI-generated analysis of the conversation. Returns `null` if analysis hasn't
  been performed yet.
</ResponseField>

<ResponseField name="conversation_status" type="string">
  Current status: `IN_PROGRESS`, `COMPLETED`, `DISCONNECTED`, or `FAILED`
</ResponseField>

<ResponseField name="notes" type="string | null">
  Additional notes or annotations for the conversation
</ResponseField>

<ResponseField name="conversation_transcript" type="array | null">
  Array of conversation messages. Each message contains: - `role`: `user` or
  `assistant` - `content`: The message text - `timestamp`: ISO 8601 timestamp
</ResponseField>

<ResponseField name="created_by" type="string | null">
  User ID who created/initiated the conversation
</ResponseField>

<ResponseField name="conversation_metadata" type="object">
  Metadata associated with the conversation. For CHAT type includes
  `last_activity` and `session_status`. For TELEPHONY includes
  `to_mobile_number`, `from_mobile_number`, `calling_type`,
  `telephony_provider`, `conversation_recording_url`, and
  `conversation_duration`.
</ResponseField>

<ResponseField name="created_at" type="datetime">
  Timestamp when the conversation was created
</ResponseField>

<ResponseField name="updated_at" type="datetime">
  Timestamp of the last update to the conversation
</ResponseField>

<ResponseField name="id" type="string">
  Internal MongoDB document ID
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.eigi.ai/v1/public/conversations/a28e7071-508e-4d45-8887-085531aafaba" \
    -H "X-API-Key: vk_your_api_key_here"
  ```

  ```python Python theme={null}
  import requests

  conversation_id = "a28e7071-508e-4d45-8887-085531aafaba"
  headers = {
      "X-API-Key": "vk_your_api_key_here"
  }

  response = requests.get(
      f"https://api.eigi.ai/v1/public/conversations/{conversation_id}",
      headers=headers
  )

  conversation = response.json()
  print(conversation)
  ```

  ```javascript Node.js theme={null}
  const axios = require("axios");

  const conversationId = "a28e7071-508e-4d45-8887-085531aafaba";

  const response = await axios.get(
    `https://api.eigi.ai/v1/public/conversations/${conversationId}`,
    {
      headers: {
        "X-API-Key": "vk_your_api_key_here",
      },
    }
  );

  console.log(response.data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "agent_id": "68ea2517dbb84c09bae1ba0a",
    "conversation_id": "a28e7071-508e-4d45-8887-085531aafaba",
    "conversation_type": "CHAT",
    "conversation_analysis": null,
    "conversation_status": "IN_PROGRESS",
    "notes": null,
    "conversation_transcript": [
      {
        "role": "user",
        "content": "hi",
        "timestamp": "2025-12-03T14:14:23.735228+00:00"
      },
      {
        "role": "assistant",
        "content": "Hi there! How can I help you today?",
        "timestamp": "2025-12-03T14:14:23.738544+00:00"
      },
      {
        "role": "user",
        "content": "who are you ?",
        "timestamp": "2025-12-03T14:14:46.605904+00:00"
      },
      {
        "role": "assistant",
        "content": "I am a large language model, trained by Google.",
        "timestamp": "2025-12-03T14:14:46.610178+00:00"
      }
    ],
    "created_by": null,
    "conversation_metadata": {
      "last_activity": "2025-12-03T14:15:20.985321+00:00",
      "session_status": "active"
    },
    "created_at": "2025-12-03T14:14:22.719000",
    "updated_at": "2025-12-03T14:15:20.985000",
    "id": "69316c7d6519e8d49433e40b"
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "detail": "Invalid API key"
  }
  ```

  ```json 403 - Forbidden theme={null}
  {
    "detail": "API key owner doesn't have access to this conversation"
  }
  ```

  ```json 404 - Not Found theme={null}
  {
    "detail": "Conversation not found"
  }
  ```

  ```json 500 - Internal Server Error theme={null}
  {
    "detail": "Internal Server Error: [error details]"
  }
  ```
</ResponseExample>

## Error Responses

## Status Codes

| Status Code | Description                                            |
| ----------- | ------------------------------------------------------ |
| 200         | Successfully retrieved conversation                    |
| 401         | Missing, invalid, inactive, or expired API key         |
| 403         | API key owner doesn't have access to this conversation |
| 404         | Conversation not found                                 |
| 500         | Internal server error                                  |

## Use Cases

<AccordionGroup>
  <Accordion title="Retrieve Call Results">
    After initiating an outbound call, use this endpoint to fetch the complete
    transcript, analysis, and outcome of the conversation.
  </Accordion>

  <Accordion title="Monitor Active Calls">
    Check the status and real-time transcript of ongoing conversations to
    monitor agent performance.
  </Accordion>

  <Accordion title="Extract Conversation Data">
    Pull conversation data for analytics, reporting, or integration with CRM
    systems.
  </Accordion>

  <Accordion title="Quality Assurance">
    Review conversation transcripts and analysis for quality assurance and agent
    training purposes.
  </Accordion>
</AccordionGroup>

## Notes

* Only conversations associated with agents owned by the API key holder can be accessed
* Conversation data is retained for 90 days by default (configurable in settings)
* Real-time transcripts are available for ongoing conversations
* Analysis data is generated automatically after conversation completion


## OpenAPI

````yaml GET /v1/public/conversations/{conversation_id}
openapi: 3.0.0
info:
  title: eigi.ai API
  description: REST API for managing AI voice agents and conversations
  version: 1.0.0
  contact:
    email: buddy@eigi.ai
    url: https://eigi.ai
servers:
  - url: https://api.eigi.ai
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /v1/public/conversations/{conversation_id}:
    get:
      tags:
        - Conversations
      summary: Get Conversation by ID
      description: >-
        Retrieve detailed information about a specific conversation using its
        unique ID
      operationId: getConversation
      parameters:
        - name: conversation_id
          in: path
          required: true
          description: The unique identifier (UUID format) of the conversation to retrieve
          schema:
            type: string
          example: 35d33a43-176c-405c-92bf-db972035df28
      responses:
        '200':
          description: Successfully retrieved conversation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - API key owner doesn't have access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Conversation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    Conversation:
      type: object
      properties:
        conversation_id:
          type: string
          description: Unique identifier for the conversation
        agent_id:
          type: string
          description: ID of the agent that handled this conversation
        conversation_type:
          type: string
          enum:
            - DAILY
            - TELEPHONY
            - WHATSAPP
            - CHAT
          description: Type of conversation
        conversation_status:
          type: string
          enum:
            - IN_PROGRESS
            - COMPLETED
            - DISCONNECTED
            - FAILED
          description: Current status of the conversation
        calling_type:
          type: string
          enum:
            - INBOUND
            - OUTBOUND
          description: Direction of the call
        mobile_number:
          type: string
          description: Phone number involved in the conversation
        duration:
          type: number
          description: Total duration of the conversation in seconds
        created_at:
          type: string
          format: date-time
          description: Timestamp when the conversation was created
        updated_at:
          type: string
          format: date-time
          description: Timestamp of the last update
        transcript:
          type: array
          items:
            type: object
          description: Array of conversation messages
        analysis:
          type: object
          description: AI-generated analysis of the conversation
        metadata:
          type: object
          description: Custom metadata
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Error message
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        API key for authentication. Get your API key from the eigi.ai Dashboard
        under Settings → API Keys.

````