# List voice calls

> List voice calls for this project, most recent first. Transcripts are omitted from the list; fetch a single call to get its transcript.

`GET https://api.zavu.dev/v1/calls`

List voice calls for this project, most recent first. Transcripts are omitted from the list; fetch a single call to get its transcript.

## Parameters

- `status` (query, string) One of: `queued`, `ringing`, `in_progress`, `completed`, `failed`, `busy`, `no_answer`, `canceled`.
- `direction` (query, string) One of: `inbound`, `outbound`.
- `senderId` (query, string): Keep only calls placed or received by this sender.
- `limit` (query, integer)
- `cursor` (query, string)

## Responses

### 200

List of voice calls.

- `items` (object[], required)
  - `id` (string, required)
  - `direction` (string, required): Whether the call was placed by Zavu (outbound) or received from a caller (inbound). One of: `inbound`, `outbound`.
  - `from` (string, required): Caller phone number in E.164 format. Your sender's number for outbound calls; the caller's number for inbound calls.
  - `to` (string, required): Callee phone number in E.164 format.
  - `status` (string, required): Lifecycle status of a voice call. - `queued`: outbound call created, not yet dialing. - `ringing`: dialing (outbound) or received and ringing (inbound). - `in_progress`: answered, the agent is connected. - `completed`: ended after a conversation. - `failed`: could not be completed. - `busy`: the line was busy. - `no_answer`: rang but was not answered. - `canceled`: canceled before it was answered. One of: `queued`, `ringing`, `in_progress`, `completed`, `failed`, `busy`, `no_answer`, `canceled`.
  - `endReason` (string, nullable): Why the call ended (e.g. `agent_ended`, `max_duration`, `transfer`, `hangup`). Present once the call is no longer active.
  - `answeredAt` (string<date-time>, nullable): When the call was answered.
  - `endedAt` (string<date-time>, nullable): When the call ended.
  - `durationSeconds` (integer, nullable): Billable talk time in seconds, measured from answer to hangup.
  - `turnCount` (integer, nullable): Number of conversation turns exchanged during the call.
  - `transcript` (object[]): Ordered transcript of the call. Included when retrieving a single call; omitted from list responses.
    - `seq` (integer, required): Ordinal position of the turn within the call, starting at 0.
    - `role` (string, required): Who produced the turn. `tool` records a tool call the agent made during the conversation. One of: `user`, `assistant`, `tool`.
    - `text` (string, required): Transcribed speech for `user` and `assistant` turns, or a JSON summary of the tool call for `tool` turns.
    - `startedAt` (string<date-time>, nullable): When the turn started.
    - `endedAt` (string<date-time>, nullable): When the turn ended.
  - `cost` (number, nullable): Total cost of the call in USD, combining the managed voice pipeline per-minute charge, telephony, and, on an agent that runs a premium model, that model's tokens. Available once the call has ended. Tokens are charged between 30 minutes and 24 hours after the call ends, so the figure can grow until then.
  - `metadata` (object): Arbitrary metadata you attached when creating the call.
    - `{key}` (string)
  - `createdAt` (string<date-time>, required)
  - `updatedAt` (string<date-time>)
- `nextCursor` (string, nullable)

### 400

Invalid query parameters: an unknown `status` or `direction`, or a `limit` outside 1-100.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

### 401

Unauthorized.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

## Example

```bash
curl -X GET "https://api.zavu.dev/v1/calls" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"
```

```typescript
import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({ apiKey: process.env.ZAVUDEV_API_KEY });

const result = await zavu.calls.list();

console.log(result);
```