---
title: "List calls of a lead"
method: GET
path: "/v1.0/calls"
tags: ["Calls"]
---

# List calls of a lead

`GET /v1.0/calls`

Returns call records attached to the given lead, with pagination metadata.

Notes:
- leadId is required and must be > 0; otherwise 404 LEAD_NOT_FOUND.
- Caller must have manage permission on the lead; otherwise 400 PERMISSION_DENIED.
- total in _metadata reflects the full result size before pagination.

## Query parameters

- `limit` integer
- `offset` integer
- `leadId` integer, required

## Headers

- `Authorization` string, required

## Response `200`

Page of call records with pagination metadata.

- CallListResponseV1 — Response for GET /v1.0/calls: a page of call records with pagination metadata.
  - `get_metadata` MetaData — Pagination metadata (offset, limit, total, collection).
    - `collection` string — The element of the array
    - `limit` integer — Quantitative limitation of responded elements
    - `offset` integer — Start index of the responded elements
    - `total` integer — The sum of retrieved elements
    - `scrollId` string — Scroll ID for the search. You can then use the scroll ID to retrieve the next batch of results for the request.
  - `calls` CallResponse[] — Call records on this page.
    - `id` integer — ID of the call.
    - `dialerCallRecordId` integer — Internal dialer call record ID.
    - `userId` integer — User ID of the agent on the call.
    - `userPhoneNumber` string — Phone number used by the agent.
    - `leadId` integer — ID of the lead on the call.
    - `leadPhoneNumber` string — Phone number of the lead.
    - `direction` 'Outbound' | 'Inbound' — Direction of the call from the agent's point of view.
    - `status` 'Completed' | 'Missed' | 'Failed' | 'Busy' | 'NoAnswer' | 'VoiceMail' — Final call status.
    - `startTime` string — Start time of the call, formatted as 'yyyy-MM-dd HH:mm:ss' in UTC.
    - `endTime` string — End time of the call, formatted as 'yyyy-MM-dd HH:mm:ss' in UTC.
    - `duration` integer — Call duration in seconds.
    - `callingOutcome` 'Talked' | 'VoiceMessage' | 'NoAnswer' | 'BadNumber' | 'DNCNumber' | 'DNCContact' — Outcome tag assigned by the agent.
    - `rateScore` integer — Agent's subjective rating of the call, 0-5.
    - `recordingSwitch` boolean — Whether the call was recorded.
    - `showUserNumber` string — Phone number displayed to the lead (caller ID).
    - `createTime` string — Creation time of the call record, formatted as 'yyyy-MM-dd HH:mm:ss' in UTC.
    - `updateTime` string — Last-updated time of the call record, formatted as 'yyyy-MM-dd HH:mm:ss' in UTC.
    - `note` string — Free-text note entered by the agent for the call.
    - `isMachineAnswered` boolean — Whether the call was answered by a voicemail / answering machine.
    - `price` number, double — Cost of the call in USD.
    - `agentId` integer — User ID of the related agent.
    - `elapsedTime` string — Time from dialing to connection, formatted as 'mm:ss' or similar.

## Other responses

- `400` — Caller has no access to the lead (20017 PERMISSION_DENIED).
- `401` — Missing or invalid authentication token.
- `404` — leadId is missing, <= 0, or does not exist (20006 LEAD_NOT_FOUND).
- `500` — Internal server error.

---

[API](https://skmtc.net/lofty/apis/lofty-service-open-apis.md) · [All operations](https://skmtc.net/lofty/apis/lofty-service-open-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lofty/lofty-service-open-apis/versions/23e640467118/schema)