---
title: "Retrieve a list of Calls"
method: GET
path: "/v2/calls"
tags: ["Calls"]
---

# Retrieve a list of Calls

`GET /v2/calls`

## Request

- Base URL: `https://api.workiz.com/crm/api`
- URL: `https://api.workiz.com/crm/api/v2/calls`
- Auth: none declared. Required headers: `Authorization`
- TypeScript: <https://skmtc.dev/workiz/apis/developer-api/docs/v2/calls/get.ts> (a function with typed inputs; its response is checked against the schema)

> **Beta:** Breaking changes may occur without notice.

Retrieves a paginated list of Calls, newest first by default. When no date filter is provided, results default to the last 30 days. Pass `dateProperty`, `dateOperator`, and `date` together to override this default. Dates are in the account timezone. The applied range is always returned in the `dateRange` field of the response. Only the first 10000 results of a query can be paged through.

## Query parameters

- `pageSize` number
- `page` number
- `field` 'createdAt' | 'duration'
- `order` 'ASC' | 'DESC'
- `direction` string[]
- `status` 'answered' | 'missed' | 'voicemail' | 'active' | 'geniusAnswering'
- `userId` string[]
- `clientId` string[]
- `jobId` string[]
- `leadId` string[]
- `adGroupId` string[]
- `tags` string[]
- `sentiment` string[]
- `intent` string[]
- `durationOperator` 'under' | 'over'
- `duration` number
- `dateProperty` 'created'
- `dateOperator` 'prev' | 'next' | 'between'
- `date` string

## Headers

- `Authorization` string, required

## Response `200`

A paginated list of Calls, with the date range the results are limited to.

- ResponseCallsV2Dto
  - `pageSize` number: The maximum number of items returned per page.
  - `page` number: The current page number.
  - `totalResults` number: The total number of results.
  - `hasMore` boolean: Whether there are more results.
  - `data` ResponseCallV2Dto[]: A list of Calls.
    - `id` string: The ID of the call (prefix `CAL-`).
    - `direction` 'inbound' | 'outgoing': The direction of the call.
    - `from` string: The phone number the call was made from.
    - `to` string: The phone number the call was made to. For call masking calls, this is the number the call was connected to, not the masking number.
    - `callMaskingNumber` string, nullable: The call masking number the call was placed through. `null` when the call did not use call masking.
    - `duration` number: The duration of the call in seconds.
    - `status` 'answered' | 'missed' | 'voicemail' | 'active' | 'geniusAnswering': The status of the call: `active` while the call is in progress or on hold, `geniusAnswering` when Genius Answering handled it, `voicemail` when the caller left a voicemail, `answered` when a person answered and `missed` otherwise.
    - `hasRecording` boolean: Whether a recording is available for the call.
    - `flowName` string, nullable: The name of the call flow that handled the call. Calls placed through call masking show `Call Masking`.
    - `adGroupId` string, nullable: The ID of the ad group of the called number (prefix `AG-`).
    - `clientId` string, nullable: The ID of the client on the call (prefix `CL-`). `null` when the caller is unknown.
    - `clientName` string, nullable: The name of the client on the call, as recorded on the call.
    - `jobId` string, nullable: The ID of the job linked to the call (prefix `JOB-`).
    - `leadId` string, nullable: The ID of the lead linked to the call (prefix `LD-`).
    - `answeredByUserId` string, nullable: The ID of the user who answered the call (prefix `USR-`).
    - `answeredByUserName` string, nullable: The name of the user who answered the call, as recorded on the call.
    - `calledByUserId` string, nullable: The ID of the user who placed the call (prefix `USR-`).
    - `calledByUserName` string, nullable: The name of the user who placed the call, as recorded on the call.
    - `tags` string[]: A list of tag IDs on the call (prefix `TAG-`).
    - `insights` ResponseCallInsightsV2Dto
      - `sentiment` 'great' | 'positive' | 'neutral' | 'negative', nullable: The overall sentiment of the call.
      - `intent` 'booking' | 'callbackRequest' | 'existingBooking' | 'spam' | 'other', nullable: The detected intent of the caller.
      - `dispatcherScore` number, nullable: The dispatcher score of the call, from 1 to 100.
      - `objection` 'price' | 'serviceNotOffered' | 'outOfServiceArea' | 'noAvailability' | 'Dispatcher experience issue' | 'notReadyToBook' | 'Callback needed' | 'disconnected' | 'other', nullable: The objection raised by the caller.
      - `pricingDiscussed` boolean: Whether pricing was discussed on the call.
      - `booked` boolean: Whether the call resulted in a booking.
    - `updatedAt` string, nullable: The date and time the call was last updated, in the account timezone.
    - `createdAt` string: The date and time the call started, in the account timezone.
  - `dateRange` ResponseCallsDateRangeV2Dto
    - `dateProperty` 'created': The date field the results are filtered by.
    - `from` string, nullable: The first date included in the results. `null` when the range is open ended.
    - `to` string, nullable: The last date included in the results. `null` when the range is open ended.

## Other responses

- `400`: Invalid sort field, order direction, filter value, incomplete/invalid date filters, or a page beyond the first 10000 results.
- `401`: Missing or invalid authentication token.
- `403`: The API key does not have permission to access this resource.
- `404`: A provided user, client, job, lead, or ad group ID is invalid.
- `429`: Rate limit exceeded.

## Changes

- **2026-10-06** `fd96151569a1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/workiz/apis/developer-api/changes/v2/calls/get.md)

---

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