---
title: "Get All Calls"
method: GET
path: "/v2/calls"
tags: ["Calls"]
---

# Get All Calls

`GET /v2/calls`

## Request

- Base URL: `https://api.carecycle.ai`
- URL: `https://api.carecycle.ai/v2/calls`
- Auth: API key in header `x-api-key`

Get paginated calls for authenticated client with descriptive field names

## Query parameters

- `page` number
- `perPage` number
- `sortBy` 'createdAt' | 'callerId' | 'direction' | 'assistantType' | 'duration' | 'disposition' | 'customerName' | 'campaignName' | 'agentName' | 'sourceName'
- `sortDirection` 'asc' | 'desc'
- `sortCustomFieldKey` string
- `customFieldKeys` string
- `search` string: Search query: matches customer name, phone number, or disposition
- `customerId` string, uuid: Filter calls by customer ID for exact customer call history
- `campaignIds` string: Optional array of campaign IDs to filter calls by specific campaigns (comma-separated string)
- `agentUserIds` string: Optional array of agent user IDs to filter calls by specific softphone agents (comma-separated string)
- `durationOperator` '<=' | '>=': Duration filter operator (less than or equal, greater than or equal)
- `durationValue` number: Duration value in seconds to filter by
- `direction` 'inbound' | 'outbound': Filter by call direction
- `callType` 'voice_ai' | 'softphone': Filter by call type: Voice AI or Softphone
- `startDate` string, date-time: Start date-time for call range filtering. ISO 8601 timestamp
- `endDate` string, date-time: End date-time for call range filtering. ISO 8601 timestamp
- `excludeDispositions` string: Array of disposition names to exclude from results (comma-separated string)
- `includeDispositions` string: Array of disposition names to limit results to (comma-separated string). Combines with excludeDispositions when both are sent.
- `excludeSources` string: Array of source ids to exclude from results (comma-separated string)
- `includeTestCalls` 'true' | 'false': When true, test calls are included in results. Default behavior is to exclude test calls.
- `connectedCallsOnly` 'true' | 'false': Filter for connected calls only using disposition outcome types, with a legacy name fallback. Default behavior is to include all calls.
- `includeErrorDispositions` 'true' | 'false': Deprecated compatibility parameter. Error dispositions are always excluded, regardless of this value.
- `includeTotal` 'true' | 'false': When false, skips the exact count so the page can return independently. Use GET /v2/calls/count for the total.

## Response `200`

GET /v2/calls Positive response

- GetV2CallsPositiveResponse
  - `itemsTotal` number, required
  - `currentPage` number, required
  - `nextPage` number, nullable, required
  - `prevPage` number, nullable, required
  - `items` object[], required
    - `id` string, uuid, required
    - `disposition` string, nullable, required
    - `callerId` string, nullable, required
    - `testFlag` boolean, nullable, required
    - `campaignId` string, uuid, nullable, required
    - `transferConfigId` string, uuid, nullable, required
    - `twilioSid` string, nullable, required
    - `service` 'vapi' | 'mobius' | 'softphone' | 'campaign_test' | 'null', nullable, required
    - `campaignName` string, nullable, required
    - `campaignIsReceptionist` boolean, required
    - `agentName` string, nullable, required
    - `customerId` string, nullable, required
    - `customerName` string, nullable, required
    - `customerStatus` 'Lead' | 'Active' | 'Inactive' | 'null', nullable, required
    - `createdAt` string, date-time, required: Call creation time. ISO 8601 timestamp
    - `duration` string, required: Formatted duration like '2m 30s'
    - `assistantType` string, nullable, required
    - `successEvaluation` string, nullable, required
    - `summary` string, nullable, required
    - `transcript` string, nullable, required
    - `detectionFlags` object, nullable, required
      - `appointment` object, nullable, required
        - `detected` boolean, nullable, required
        - `confidence` 'low' | 'medium' | 'high' | 'null', nullable, required
      - `inquiry` object, nullable, required
        - `detected` boolean, nullable, required
        - `confidence` 'low' | 'medium' | 'high' | 'null', nullable, required
      - `dnc` object, nullable, required
        - `detected` boolean, nullable, required
        - `confidence` 'low' | 'medium' | 'high' | 'null', nullable, required
    - `direction` 'inbound' | 'outbound' | 'null', nullable, required
    - `sourceName` string, nullable, required
    - `attemptNumber` number, nullable, required
    - `ourPhoneNumber` string, nullable, required
    - `customFields` object[], required: Custom fields from the customer associated with this call
      - `fieldKey` string, required: Generated identifier for the field
      - `fieldLabel` string, required: Display name shown to users
      - `fieldDescription` string, required: Description of the field's purpose
      - `fieldType` 'text' | 'number' | 'boolean' | 'date' | 'select' | 'multi_select', required: Type of data this field stores
      - `isRequired` boolean, nullable, required: Whether this field must have a value
      - `options` string[], nullable, required: Available options for select/multi-select fields
      - `validationRules` union, required: Validation rules for the custom field
        - string
        - number
        - boolean
        - object
        - unknown[]
          - unknown
      - `value` union, required: The actual value for this customer (type determined by fieldType). Dates are represented as ISO 8601 strings.
        - string
        - number
        - boolean
        - string[]
    - `participationEvents` object[], required: Softphone participation timeline: agents joining/leaving and participants added mid-call. Empty for single-agent and voice-AI calls.
      - `event` 'call_answered' | 'agent_joined' | 'agent_left' | 'participant_added' | 'call_ended' | 'audio_clip_played', required
      - `timestamp` string, date-time, required: Participation event time. ISO 8601 timestamp
      - `endedBy` 'customer' | 'agent'
      - `userId` string
      - `userName` string
      - `byUserId` string
      - `byUserName` string
      - `phoneNumber` string
      - `transferConfigId` string
      - `destinationName` string
      - `callContinued` boolean
      - `clipLabel` string
    - `transcriptEntries` object[]: Structured per-utterance transcript with speaker and timestamp. Only returned by the single-call endpoint, and only for softphone calls with a live transcript.
      - `speakerName` string, nullable
      - `speakerRole` string, nullable
      - `userId` string, nullable
      - `text` string, required
      - `timestamp` string, date-time, nullable: Transcript entry time. ISO 8601 timestamp
    - `routingResult` object
      - `outcome` string, required
      - `agentConnectedAt` string, nullable, required
      - `queuedAt` string, nullable, required
      - `fallbackReason` string, nullable, required
      - `fallbackAction` string, nullable, required
      - `terminationParty` 'caller' | 'platform' | 'not_reported', required
      - `callerEndedAfterFallback` boolean, required
      - `callbackOutcome` string, nullable, required
      - `callbackDecision` string, nullable, required
      - `callbackReason` string, nullable, required
      - `announcementCompleted` boolean, required
      - `deliveryStage` string, nullable, required
      - `trackingVersion` number, required
      - `availableAgents` number, nullable, required
    - `handoff` object: AI-to-rep warm handoff shared by both legs of the call: the AI leg, the rep leg it reached (if any), and how the handoff ended
      - `aiCallId` string, required
      - `aiDuration` string, required
      - `repCallId` string, nullable, required
      - `repName` string, nullable, required
      - `repDuration` string, nullable, required
      - `outcome` 'connected' | 'ringing' | 'no_answer' | 'caller_hung_up' | 'failed', required
      - `waitSeconds` number, nullable, required
  - `hasNextPage` boolean, required
  - `totalExact` boolean, required
  - `testNumberCalls` number: Count of test number calls in the response
  - `hasSourceTracking` boolean: Whether any campaigns have source tracking enabled

## Other responses

- `400`: GET /v2/calls Negative response 400
- `401`: GET /v2/calls Negative response 401
- `403`: GET /v2/calls Negative response 403
- `404`: GET /v2/calls Negative response 404
- `409`: GET /v2/calls Negative response 409
- `422`: GET /v2/calls Negative response 422
- `429`: GET /v2/calls Negative response 429
- `500`: GET /v2/calls Negative response 500
- `502`: GET /v2/calls Negative response 502
- `503`: GET /v2/calls Negative response 503

---

[API](https://skmtc.dev/carecycle/apis/carecycle-public-api.md) - [All operations](https://skmtc.dev/carecycle/apis/carecycle-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/carecycle/apis/carecycle-public-api/revisions/db390c743c36?raw)