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

# List Calls

> List calls for an agent using the frontend API with API-key authentication.

Retrieves a list of calls for a specific agent with comprehensive filtering and pagination options. This endpoint allows you to query call history, filter by various criteria, and paginate through results.

### Request

**Method:** `GET`\
**Endpoint:** `/api/calls/{agentId}`\
**Headers:**

* `X-Authorization`: Your API key (required)

**Path Parameters:**

* `agentId` (string, required): The ID of the agent whose calls you want to retrieve

### Notes

* Array filters can be specified multiple times in the query string to filter by multiple values
* All date parameters should be in ISO 8601 format (e.g., `2024-01-01T00:00:00Z`)
* Duration values are in seconds
* Phone numbers should be URL-encoded (e.g., `+1234567890` becomes `%2B1234567890`)
* The `total` field in the response indicates the total count of matching calls, which may be greater than the number of items returned based on the `limit` parameter

### Examples

**Basic Request:**

```bash theme={null}
curl -X GET "https://app.phonely.ai/api/calls/agent123" \
  -H "X-Authorization: your-api-key"
```

**With Pagination:**

```bash theme={null}
curl -X GET "https://app.phonely.ai/api/calls/agent123?limit=50&offset=0" \
  -H "X-Authorization: your-api-key"
```

**With Single Value Filters:**

```bash theme={null}
curl -X GET "https://app.phonely.ai/api/calls/agent123?customer_phone_number=%2B1234567890&campaign_id=campaign456" \
  -H "X-Authorization: your-api-key"
```

**With Array Filters:**

```bash theme={null}
curl -X GET "https://app.phonely.ai/api/calls/agent123?status=completed&status=in-progress&sentiment=positive" \
  -H "X-Authorization: your-api-key"
```

**With Date Range:**

```bash theme={null}
curl -X GET "https://app.phonely.ai/api/calls/agent123?start_date=2024-01-01T00:00:00Z&end_date=2024-12-31T23:59:59Z" \
  -H "X-Authorization: your-api-key"
```

**With Duration Range:**

```bash theme={null}
curl -X GET "https://app.phonely.ai/api/calls/agent123?min_duration=60&max_duration=300" \
  -H "X-Authorization: your-api-key"
```

**Complex Query (Multiple Filters):**

```bash theme={null}
curl -X GET "https://app.phonely.ai/api/calls/agent123?limit=25&offset=0&status=completed&sentiment=positive&sentiment=neutral&call_type=inbound&start_date=2024-01-01T00:00:00Z&min_duration=30" \
  -H "X-Authorization: your-api-key"
```


## OpenAPI

````yaml GET /calls/{agentId}
openapi: 3.0.1
info:
  title: Phonely API
  description: API for Phonely services including agent management and call summaries
  version: 1.0.0
servers:
  - url: https://app.phonely.ai/api
security: []
paths:
  /calls/{agentId}:
    get:
      summary: List calls by agent ID
      description: >-
        Retrieves a list of calls for a specific agent with comprehensive
        filtering and pagination options
      parameters:
        - name: agentId
          in: path
          required: true
          schema:
            type: string
          description: The ID of the agent whose calls you want to retrieve
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
          description: Maximum number of results to return
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Number of results to skip for pagination
        - name: customer_phone_number
          in: query
          required: false
          schema:
            type: string
          description: Filter by customer phone number
        - name: campaign_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by campaign ID
        - name: status
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - COMPLETED
                - FAILED
                - ENDED
                - IN_PROGRESS
          description: Filter by call status (can specify multiple values)
        - name: sentiment
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - Positive
                - Negative
                - Neutral
          description: Filter by sentiment (can specify multiple values)
        - name: call_type
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - inboundPhoneCall
                - outboundPhoneCall
                - webCall
                - dailyCall
          description: Filter by call type (can specify multiple values)
        - name: outcome
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
          description: Filter by call outcome (can specify multiple values)
        - name: ended_reason
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
          description: Filter by call ended reason (can specify multiple values)
        - name: mode
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
          description: Filter by call mode (can specify multiple values)
        - name: start_date
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter calls after this date (ISO 8601 datetime format)
        - name: end_date
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter calls before this date (ISO 8601 datetime format)
        - name: min_duration
          in: query
          required: false
          schema:
            type: number
          description: Minimum call duration in seconds
        - name: max_duration
          in: query
          required: false
          schema:
            type: number
          description: Maximum call duration in seconds
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCallsResponse'
        '400':
          description: Agent ID is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - You do not have access to this agent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ListCallsResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CallItem'
          description: Array of call objects matching the filter criteria
        total:
          type: integer
          description: >-
            Total number of calls matching the filters (not limited by
            pagination)
        limit:
          type: integer
          description: The limit value used in the request
        offset:
          type: integer
          description: The offset value used in the request
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error code or identifier
        message:
          type: string
          description: Detailed error message
    CallItem:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the call
        agentId:
          type: string
          description: ID of the agent that handled the call
        business_phone_number:
          type: string
          description: The business phone number used for the call
        customer_phone_number:
          type: string
          description: The customer's phone number
        started_at:
          type: string
          format: date-time
          description: ISO 8601 datetime when the call started
        ended_at:
          type: string
          format: date-time
          description: ISO 8601 datetime when the call ended
        duration:
          type: number
          description: Call duration in seconds
        status:
          type: string
          enum:
            - COMPLETED
            - FAILED
            - ENDED
            - IN_PROGRESS
          description: Call status
        recording_url:
          type: string
          description: URL to access the call recording
        ended_reason:
          type: string
          description: Reason why the call ended
        type:
          type: string
          enum:
            - inboundPhoneCall
            - outboundPhoneCall
            - webCall
            - dailyCall
          description: Type of call
        mode:
          type: string
          description: Call mode
        read:
          type: boolean
          description: Whether the call has been read
        c_sentiment:
          type: string
          enum:
            - Positive
            - Negative
            - Neutral
          description: Customer sentiment analysis result
        c_outcome:
          type: string
          description: Call outcome classification
        c_topic:
          type: string
          description: Topic identified during the call
        ab_test_type:
          type: string
          description: A/B test variant
        ab_test_id:
          type: string
          description: ID of the A/B test
        ab_test_success:
          type: boolean
          description: Whether the A/B test was successful
        draft_agent_version:
          type: string
          nullable: true
          description: Version of draft agent used, if any
        draft_agent_id:
          type: string
          nullable: true
          description: ID of draft agent used, if any
        workflow_path_history:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowAction'
          description: Array of workflow actions executed during the call
        campaign_id:
          type: string
          nullable: true
          description: ID of the campaign associated with the call, if any
    WorkflowAction:
      type: object
      properties:
        actionId:
          type: string
          description: ID of the workflow action
        workflowId:
          type: string
          description: ID of the workflow
        readableName:
          type: string
          description: Human-readable name of the action
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Authorization

````