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

# List Calls



## OpenAPI

````yaml GET /calls
openapi: 3.1.0
info:
  title: Yappr API
  description: >
    Create and manage AI voice agents, purchase phone numbers, configure tools,
    and initiate calls — all via REST.
  version: 1.0.0
  contact:
    url: https://goyappr.com
servers:
  - url: https://api.goyappr.com
    description: Production
security:
  - apiKey: []
paths:
  /calls:
    get:
      tags:
        - Calls
      summary: List calls
      operationId: listCalls
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
            maximum: 100
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
        - in: query
          name: agent_id
          schema:
            type: string
            format: uuid
          description: Filter by agent
        - in: query
          name: status
          schema:
            type: string
          description: >-
            Filter by call status (e.g. completed, failed, in_progress,
            no_answer, dnc_blocked)
        - in: query
          name: direction
          schema:
            type: string
            enum:
              - inbound
              - outbound
              - web_call
        - in: query
          name: callee
          schema:
            type: string
          description: >-
            Filter by callee (destination) phone number in E.164. Useful for
            counting prior attempts to a specific lead — e.g. retry-throttle
            logic: `?agent_id=X&callee=+972Y&from=TODAY` then read `data.length`
            directly.
          example: '+972501234567'
        - in: query
          name: caller
          schema:
            type: string
          description: Filter by caller (source) phone number in E.164.
          example: '+972551234567'
        - in: query
          name: from
          schema:
            type: string
            format: date-time
          description: Return calls created on or after this timestamp
        - in: query
          name: to
          schema:
            type: string
            format: date-time
          description: Return calls created on or before this timestamp
      responses:
        '200':
          description: List of calls
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        agent_id:
                          type: string
                          format: uuid
                        from:
                          type: string
                        to:
                          type: string
                        direction:
                          type: string
                        status:
                          type: string
                        started_at:
                          type: string
                          format: date-time
                          nullable: true
                        ended_at:
                          type: string
                          format: date-time
                          nullable: true
                        duration_seconds:
                          type: integer
                          nullable: true
                        created_at:
                          type: string
                          format: date-time
                        ended_by:
                          type: string
                          enum:
                            - caller
                            - agent
                            - system
                            - unknown
                          nullable: true
                          description: >-
                            Who terminated the call. First-write-wins (a
                            specific value like 'system' from voicemail
                            detection is not overwritten by a later generic
                            'caller').
                        disconnect_reason:
                          type: string
                          nullable: true
                          description: >-
                            User-friendly reason the call ended (e.g.
                            'Completed', 'Voicemail detected').
                            First-write-wins.
                        transferred_at:
                          type: string
                          format: date-time
                          nullable: true
                          description: >-
                            When the call was transferred (set only if
                            status='transferred').
                        transfer_target:
                          type: string
                          nullable: true
                          description: E.164 number or SIP URI the call was transferred to.
                        recording_url:
                          type: string
                          nullable: true
                          description: >-
                            Permanent signed URL for the call recording. Opens
                            directly in a browser or audio player — redirects
                            (302) to the audio file. No additional
                            authentication required.
                        tool_calls_count:
                          type: integer
                          description: >-
                            Number of LLM-decided tool invocations during the
                            call. Always 0 for flow-agent calls — see
                            flow_tool_fires_count instead.
                        flow_steps_count:
                          type: integer
                          description: >-
                            Number of nodes visited during the call. 0 for
                            prompt-agent calls. Same node visited twice counts
                            twice.
                        flow_tool_fires_count:
                          type: integer
                          description: >-
                            Number of tool_call nodes that fired during the
                            call. 0 for prompt-agent calls.
                        disposition:
                          nullable: true
                          description: >-
                            Full Disposition object. Present only when a
                            disposition has been assigned to the call.
                          allOf:
                            - $ref: '#/components/schemas/Disposition'
                        lead:
                          nullable: true
                          description: >-
                            Full Lead object. Present only when a matched lead
                            exists for this call.
                          allOf:
                            - $ref: '#/components/schemas/Lead'
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                      limit:
                        type: integer
                      offset:
                        type: integer
                      has_more:
                        type: boolean
components:
  schemas:
    Disposition:
      type: object
      properties:
        id:
          type: string
          format: uuid
        label:
          type: string
        color:
          type: string
          nullable: true
          example: '#22c55e'
        position:
          type: integer
        is_protected:
          type: boolean
          description: Protected dispositions cannot be deleted.
        created_at:
          type: string
          format: date-time
    Lead:
      type: object
      properties:
        id:
          type: string
          format: uuid
        phone_number:
          type: string
          example: '+972501234567'
        name:
          type: string
          nullable: true
        email:
          type: string
          format: email
          nullable: true
        source:
          type: string
          example: api
          description: >-
            How the lead was created: 'api', 'manual', or 'auto' (from inbound
            call).
        tags:
          type: array
          items:
            $ref: '#/components/schemas/LeadTag'
        long_term_context:
          type: string
          nullable: true
          description: >-
            AI memory for this lead. Injected into the agent's system prompt at
            call time when lead_memory_enabled is true on the agent.
        metadata:
          type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    LeadTag:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
          nullable: true
        color:
          type: string
          nullable: true
        sort_order:
          type: integer
        created_at:
          type: string
          format: date-time
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Your Yappr API key (e.g. `ypr_live_...`). Generate one in the dashboard
        under **Settings → API Keys**.

````