> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getvoxai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getvoxai.com/_mcp/server.

# List calls

GET https://api.getvoxai.com/v1/calls

Returns the calls of the organization in a period, newest first by default, one page at a time. Each item has times, duration, direction, status, the two phone numbers, the agent and the outcome of the report card. The summary, the collected data and the transcript are never in the list: read them on the single call. There is no filter by caller number on purpose (a phone number must not travel in a URL): to find the data of a person use `POST /caller-requests/search`. Required scope: `calls:read`. With a test key (`vx_test_`) it behaves exactly as with a live key and consumes nothing.

Reference: https://docs.getvoxai.com/api-reference/calls/list

## Authentication

- `Authorization` header (bearer token, required) — API key created by an Owner or Admin of the organization. Never in the query string.

## Request

### Query parameters

- `period` (enum, optional) — The period to read, in the `timezone`. Default `7d`. `today`: from midnight to now. `7d`, `30d`: the last 7 or 30 days, today included. `last_month`: the previous calendar month. `6m`, `12m`: the last 6 or 12 months. `custom`: from `from` to `to`, at most 13 months.
  - Allowed values: `today`, `7d`, `30d`, `last_month`, `6m`, `12m`, `custom`
- `from` (string, optional) — First day of a `custom` period, YYYY-MM-DD, in the `timezone`. Only with `period=custom`.
- `to` (string, optional) — Last day of a `custom` period, YYYY-MM-DD, included. Only with `period=custom`.
- `timezone` (string, optional) — IANA time zone the period is computed in, for example `Europe/Rome` (default). It decides where days start and end.
- `status` (string, optional) — Only calls with one of these statuses, comma-separated: `completed`, `interrupted`, `failed`, `in_progress`, `forwarded`, `missed_lines_busy`, `missed_quota`, `missed_suspended`, `missed_platform`, `missed_agent_suspended`. `completed` also matches calls transferred to a person (`transferred` is not a filter value). The meaning of each value is in `status` of the response.
- `missed` (boolean, optional) — `true`: only calls rejected before an agent answered (`missed_*`). `false`: only answered calls. Omitted: both.
- `agent_id` (string, optional) — Only the calls handled by this agent.
- `direction` (enum, optional) — Only one channel. `inbound`: phone calls received. `outbound`: phone calls made by an agent. `web`: conversations in the web widget.
  - Allowed values: `inbound`, `outbound`, `web`
- `line` (string, optional) — Only the calls on this phone line of the organization (not the caller number), in international format, for example `+390212345678`. The lines are listed by `GET /lines`.
- `report_card` (enum, optional) — Only calls with this report card outcome: `positive`, `needs_review`, `negative`, or `not_evaluated` (no report card, or not computed yet).
  - Allowed values: `positive`, `needs_review`, `negative`, `not_evaluated`
- `has_handoff` (boolean, optional) — `true`: only calls that passed between agents of a team. `false` or omitted: every call.
- `order` (enum, optional, default: desc) — Order by start time: `desc` newest first (default), `asc` oldest first. The cursor is tied to the order: do not change it between pages.
  - Allowed values: `desc`, `asc`
- `limit` (integer, optional, default: 20) — Maximum number of items in the page, from 1 to 100. Default 20.
- `cursor` (string, optional) — Opaque cursor from `next_cursor` of the previous page, to read the next one. Pass it back unchanged, with the same filters; omit it for the first page.

### Headers

- `VoxAI-Version` (enum, optional) — API version for this request; defaults to the version the key is pinned to.
  - Allowed values: `2026-10-01`

## Response

### 200

Successful response.

- `data` (list of CallsGetResponsesContentApplicationJsonSchemaDataItems, required) — The items of this page, in the requested order.
- `has_more` (boolean, required) — `true` if there are more items after this page.
- `next_cursor` (string, required, nullable) — Pass it as `cursor` to read the next page; `null` on the last page.

## Errors

### 400 Bad Request Error

Possible errors: * `invalid_api_version`: The `VoxAI-Version` header names a version that does not exist. Use one of the versions listed in the `VoxAI-Version` parameter, or omit the header to use the version the key is pinned to. * `invalid_cursor`: The `cursor` was not produced by this list, belongs to another filter or order, or is corrupted. Restart from the first page without `cursor`, and pass `next_cursor` back unchanged with the same filters. * `invalid_line`: The `line` filter is not a valid phone number. Pass one of the numbers returned by `GET /lines`, in international format. * `invalid_period`: The period is not valid: `from` or `to` with a named period, `custom` without both, a day that does not exist, or `from` after `to`. Use a named `period`, or `period=custom` with `from` and `to` (YYYY-MM-DD, `to` included). * `invalid_request`: The path, query or body does not match the schema of the operation: a missing or unknown field, a wrong type, a value out of range. Fix the request. `details` lists each problem as `{ location, path, message }`: `location` is `params`, `query` or `body` and `path` points to the field. * `invalid_timezone`: The `timezone` is not a known IANA time zone. Use a name such as `Europe/Rome`, or omit it (default `Europe/Rome`). * `period_too_long`: The `custom` period is longer than 13 months. Split the range into shorter periods.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 401 Unauthorized Error

Possible errors: - `invalid_api_key`: The `Authorization` header is missing, malformed, or carries a key that does not exist, was revoked or has expired. Send `Authorization: Bearer vx_live_…` (or `vx_test_…`) with an active key. Create a new key in the app if this one expired.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 403 Forbidden Error

Possible errors: - `feature_not_available`: The plan of the organization does not include the API, or the feature this operation needs. Upgrade the plan in the app. Reads and deletions stay available after a downgrade. - `insufficient_scope`: The key does not have the scope this operation requires (written in the description of the operation). Create a key with the required scope (an Owner or Admin can do it in the app), or ask for the scope to be added. - `ip_not_allowed`: The key has an IP allow-list and the request comes from an address that is not on it. Call from an allowed address, or add this address to the key in the app. - `organization_suspended`: The organization that owns the key is suspended. Contact the organization Owner: nothing can be done through the API until the organization is active again.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 429 Too Many Requests Error

Possible errors: - `rate_limited`: Too many requests: over the per-minute limit of this key or of the whole organization (see `rate_limits` in `GET /me`), or over a limit of the operation itself, such as the hourly limit on webhook tests and resends. Wait for the number of seconds in the `Retry-After` header, then retry. Spread requests over time.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 500 Internal Server Error

Possible errors: - `internal_error`: An unexpected error on our side. Retry once after a few seconds. For writes marked as retriable, retry with the same `Idempotency-Key`, so the operation is never done twice; for the other writes, first read the state of the resource, then retry with a NEW key only if the operation did not happen. If it persists, contact support with the `requestId`.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 503 Service Unavailable Error

Possible errors: - `api_not_configured`: The API is not enabled on this service. Contact support.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

## Types

### CallsGetResponsesContentApplicationJsonSchemaDataItems

- `object` ("call", required) — Always `call`.
- `id` (string, required) — Id of the call: use it with `GET /calls/{call_id}`, the transcript and the events.
- `started_at` (datetime, required, nullable) — When the call started, ISO 8601 UTC; `null` if it never started.
- `ended_at` (datetime, required, nullable) — When the call ended, ISO 8601 UTC; `null` while it is in progress.
- `duration_seconds` (integer, required) — Talk time in seconds. 0 for missed calls. It is not the billed time (see `GET /usage`).
- `direction` (enum, required) — `inbound`: a phone call received on a line of the organization. `outbound`: a phone call made by an agent (`POST /calls` or a campaign). `web`: a conversation in the web widget.
  - Allowed values: `inbound`, `outbound`, `web`
- `status` (enum, required) — How the call went. `completed`: the conversation ended normally. `transferred`: the agent handed the call to a person. `forwarded`: an inbound call forwarded to the business number without the agent (answering mode, or a backup number). `interrupted`: the call was cut before its natural end. `failed`: the call could not take place because of an error. `in_progress`: the call is still going on. Rejected before an agent answered: `missed_lines_busy` (all concurrent-call lines busy), `missed_quota` (plan minutes used up), `missed_suspended` (organization suspended), `missed_platform` (the service was at capacity), `missed_agent_suspended` (the agent is suspended).
  - Allowed values: `completed`, `transferred`, `forwarded`, `interrupted`, `failed`, `in_progress`, `missed_lines_busy`, `missed_quota`, `missed_suspended`, `missed_platform`, `missed_agent_suspended`
- `caller_number` (string, required, nullable) — The other party of the call, in international format: who called (inbound) or who was called (outbound). `null` on the web channel.
- `line_number` (string, required, nullable) — The phone line of the organization used by the call, in international format. `null` on the web channel.
- `agent` (CallsGetResponsesContentApplicationJsonSchemaDataItemsAgent, required, nullable) — The agent that handled the call (the first one, for calls that passed between agents); `null` if no agent took part.
- `handoff_count` (integer, required) — How many times the call passed from one agent of a team to another. 0 for calls handled by one agent.
- `report_card` (CallsGetResponsesContentApplicationJsonSchemaDataItemsReportCard, required) — The report card of the call: whether it is ready and its outcome. The criteria are on the single call.

### CallsGetResponsesContentApplicationJsonSchemaDataItemsAgent

The agent that handled the call (the first one, for calls that passed between agents); `null` if no agent took part.

- `id` (string, required) — Id of the agent.
- `name` (string, required, nullable) — Name of the agent; `null` if the agent was deleted.

### CallsGetResponsesContentApplicationJsonSchemaDataItemsReportCard

The report card of the call: whether it is ready and its outcome. The criteria are on the single call.

- `status` (enum, required) — `evaluated`: the report card is ready. `pending`: the call ended a few minutes ago and the report card is being computed. `not_evaluated`: the call has no report card (for example it was missed or too short).
  - Allowed values: `evaluated`, `pending`, `not_evaluated`
- `outcome` (enum, required) — Overall judgement of the call: `positive` (goal reached), `needs_review` (worth a look), `negative` (goal not reached). `null` while there is no report card.
  - Allowed values: `positive`, `needs_review`, `negative`

## Examples

**Response**

```json
{
  "data": [
    {
      "object": "call",
      "id": "c_7Hq2Lm9XwR4tYb8N",
      "started_at": "2026-11-16T09:41:07Z",
      "ended_at": "2026-11-16T09:44:52Z",
      "duration_seconds": 225,
      "direction": "inbound",
      "status": "completed",
      "caller_number": "+393331234567",
      "line_number": "+390212345678",
      "agent": {
        "id": "reception-studio-rossi",
        "name": "Reception Studio Rossi"
      },
      "handoff_count": 0,
      "report_card": {
        "status": "evaluated",
        "outcome": "positive"
      }
    },
    {
      "object": "call",
      "id": "c_9Zt4Wn2BcF7gHx1P",
      "started_at": "2026-11-15T16:02:31Z",
      "ended_at": "2026-11-15T16:03:40Z",
      "duration_seconds": 69,
      "direction": "inbound",
      "status": "transferred",
      "caller_number": "+393471112233",
      "line_number": "+390212345678",
      "agent": {
        "id": "reception-studio-rossi",
        "name": "Reception Studio Rossi"
      },
      "handoff_count": 0,
      "report_card": {
        "status": "evaluated",
        "outcome": "needs_review"
      }
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ0IjoiMjAyNi0xMS0xNVQxNjowMjozMVoiLCJpZCI6ImNfOVp0NFduMkJjRjdnSHgxUCJ9"
}
```

**SDK Code**

```python
import requests

url = "https://api.getvoxai.com/v1/calls"

querystring = {"direction":"inbound","limit":"2","missed":"false","period":"7d"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.getvoxai.com/v1/calls?direction=inbound&limit=2&missed=false&period=7d';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getvoxai.com/v1/calls?direction=inbound&limit=2&missed=false&period=7d"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.getvoxai.com/v1/calls?direction=inbound&limit=2&missed=false&period=7d")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.getvoxai.com/v1/calls?direction=inbound&limit=2&missed=false&period=7d")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.getvoxai.com/v1/calls?direction=inbound&limit=2&missed=false&period=7d', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.getvoxai.com/v1/calls?direction=inbound&limit=2&missed=false&period=7d");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.getvoxai.com/v1/calls?direction=inbound&limit=2&missed=false&period=7d")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```