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

# List Calls

> List call logs



## OpenAPI

````yaml get /observability/v1/call-logs/
openapi: 3.1.0
info:
  title: Cekura API
  version: v1
  description: >-
    Complete API documentation for the Cekura platform. This API provides
    endpoints for testing, observing, and evaluating AI voice agents — including
    managing agents, running evaluators, defining metrics, and analyzing call
    quality.
servers:
  - url: https://api.cekura.ai
security: []
paths:
  /observability/v1/call-logs/:
    get:
      tags:
        - observability
      summary: List call logs
      description: >-
        List **production** call logs for an agent or project. Production-only —
        test/simulation runs triggered via `run_scenarios_*` do NOT create call
        logs; use `results_list` + `runs_bulk_retrieve` for simulation data
        instead.


        Always pass `agent_id` or `project_id` to scope results — without one,
        the response may be very large. **`project_id` is required when using an
        organization-level API key.**


        **Filtering:**

        - `timestamp_from` / `timestamp_to` — ISO 8601 date range filter

        - `call_ids` — comma-separated **CallLog IDs** (integer DB IDs of call
        logs in this list response), e.g. `"123,456"`. Distinct from simulation
        `run_id`s and from each call log's own `call_id` field (which holds the
        provider's call identifier string).

        - `filters_v2` — structured JSON filter (same format as dashboard
        filters). Simple: `{"field": "success", "op": "eq", "value": true}`.
        Compound: `{"operator": "and", "conditions": [{...}, {...}]}`. Supported
        operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`,
        `startswith`, `in`, `isnull`.
      operationId: call-logs-list
      parameters:
        - name: page
          required: false
          in: query
          description: A page number within the paginated result set.
          schema:
            type: integer
        - name: page_size
          required: false
          in: query
          description: Number of results to return per page.
          schema:
            type: integer
        - in: query
          name: timestamp_from
          schema:
            type: string
            format: date-time
          description: |

            Filter results from this timestamp (e.g. 2025-01-01T00:00:00Z)
            Example: `2025-01-01T00:00:00Z`
        - in: query
          name: timestamp_to
          schema:
            type: string
            format: date-time
          description: |

            Filter results to this timestamp (e.g. 2025-01-31T23:59:59Z)
            Example: `2025-01-31T23:59:59Z`
        - in: query
          name: call_ids
          schema:
            type: string
            minLength: 1
          description: >-
            Comma-separated list of call log IDs to filter by. Example:
            `"5181749,5181752"`
        - in: query
          name: agent_id
          schema:
            type: integer
          description: >

            Filter by agent ID. Either agent_id or project_id should be
            provided.

            Example: `2142`
        - in: query
          name: project_id
          schema:
            type: integer
          description: >

            Filter by project ID. Either agent_id or project_id should be
            provided.

            **Required when using an organization-level API key** to scope
            results to a specific project.

            Example: `1376`
        - in: query
          name: assistant_id
          schema:
            type: string
            minLength: 1
          description: |

            Filter by assistant ID
            Example:
            - `"asst_1234567890"`
            - `"agent_xyz789"`
        - in: query
          name: filters_v2
          schema:
            type: string
            minLength: 1
          description: >

            Advanced JSON filters using CallLogQueryFilter format (same as
            dashboard filters).

            Supports nested AND/OR conditions, field comparisons, and related
            field filtering.


            Example - Simple filter:

            `{"field": "success", "op": "eq", "value": true}`


            Example - AND conditions:

            `{"operator": "and", "conditions": [{"field": "success", "op": "eq",
            "value": true}, {"field": "duration", "op": "gte", "value": 60}]}`


            Example - OR conditions:

            `{"operator": "or", "conditions": [{"field": "call_ended_reason",
            "op": "eq", "value": "completed"}, {"field": "call_ended_reason",
            "op": "eq", "value": "hangup"}]}`


            Supported fields: success, duration, call_id, timestamp, created_at,
            call_ended_reason, customer_number, etc.

            Supported operators: eq, neq, gt, gte, lt, lte, contains,
            startswith, in, isnull
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedCallLogListList'
          description: ''
      security:
        - api_key: []
components:
  schemas:
    PaginatedCallLogListList:
      type: object
      required:
        - count
        - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/CallLogList'
    CallLogList:
      type: object
      description: ''
      properties:
        id:
          type: integer
          readOnly: true
        duration:
          type: string
          readOnly: true
          description: |-
            Call duration in minutes in MM:SS format.
            Example: `01:10`
        success:
          type:
            - boolean
            - 'null'
          description: |-
            Whether the call was successful.
            Example: `true` or `false`
        is_reviewed:
          type: boolean
          description: |-
            Whether the call has been reviewed.
            Example: `true` or `false`
        status:
          enum:
            - success
            - failure
            - reviewed_success
            - reviewed_failure
          type: string
          x-spec-enum-id: a5dfbbcee6f2a6ce
          description: |-
            Status of the call or conversation.
            Example: `"completed"` or `"failed"`

            * `success` - Success
            * `failure` - Failure
            * `reviewed_success` - Reviewed Success
            * `reviewed_failure` - Reviewed Failure
        feedback:
          type: string
          description: |-
            Feedback about the call.
            Example: `"Great Call"`
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/CallLogListSerializerMetrics'
          readOnly: true
          description: Metrics of the call
        call_ended_reason:
          type: string
          description: |
            Reason why the call ended.
            Example: 
            - `"customer-ended-call"`
            - `"agent-ended-call"`
          maxLength: 100
        customer_number:
          type: string
          description: |
            Customer's phone number or identifier.
            Example: 
            - `"+1234567890"`
            - `"customer_abc123"`
          maxLength: 100
        agent:
          type:
            - integer
            - 'null'
          description: Agent ID
        agent_name:
          type: string
          readOnly: true
          description: Agent name
        call_id:
          type: string
          description: |-
            Unique identifier for the call.
            Example: 
            - `"call_abc123xyz"`
            - `"stereo_audio_session_456"`
          maxLength: 100
        trace_id:
          type: string
          description: >-
            OpenTelemetry trace ID (32-char hex). Set when OTel tracing is
            enabled.
          maxLength: 32
        timestamp:
          type: string
          format: date-time
          description: |-
            When the call occurred.
            Example: `2024-03-15T10:15:45Z`
        error_message:
          type:
            - string
            - 'null'
        dropoff_point:
          type: string
          description: |-
            Point in conversation where user disengaged.
            Example: `"end of conversation as no queries remaining"`
          maxLength: 1000
        topic:
          type: string
          description: |
            Topic of the call.
            Example: 
            - `"product_inquiry"`
            - `"technical_support"`
          maxLength: 1000
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: |-
            When this record was created.
            Example: `2024-03-15T10:30:45Z`
        updated_at:
          type: string
          format: date-time
          readOnly: true
          description: |-
            When this record was last updated.
            Example: `2024-03-15T10:35:11Z`
        transcript:
          type: string
          description: >
            Full text transcript of the call.

            Example: 

            ```text

            [00:01] Testing Agent: Hello. 

            [00:02] Main Agent: Hello, how can I help you today?

            [00:03] Testing Agent: Well, I mean, sure. What time exactly are we
            talking about here

            [00:04] Main Agent: 6 PM.

            [00:05] Testing Agent: Great. I'll book that for you. Just a sec.

            [00:06] Main Agent: Okay.

            ```
        transcript_object:
          type: string
          readOnly: true
          description: |-
            Structured transcript data with timestamps.
            Example: 
            ```json
            [
                {
                    "role": "Testing Agent",
                    "content": "Hello",
                    "start_time": 1.2,
                    "end_time": 1.8
                },
                {
                    "role": "Main Agent",
                    "content": "Hello, how can I help you today?",
                    "start_time": 1.8,
                    "end_time": 2.5
                }
            ]`
        evaluation:
          type: string
          readOnly: true
          description: Evaluation of the call
      required:
        - call_id
    CallLogListSerializerMetrics:
      type: object
      properties:
        id:
          type: integer
          description: Metric ID
        name:
          type: string
          description: Metric name
        type:
          type: string
          description: Metric type
        score:
          type: number
          format: double
          description: Evaluated metric score, Present if metrictype is not enum
        enum:
          type: string
          description: Metric enum, Present if type is enum
        value:
          type: string
          description: Evaluated metric value, Present if metric type is enum
      required:
        - enum
        - id
        - name
        - score
        - type
        - value
  securitySchemes:
    api_key:
      type: apiKey
      name: X-CEKURA-API-KEY
      in: header
      description: >-
        API Key Authentication. It should be included in the header of each
        request.

````