> 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 campaigns

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

Returns the outbound campaigns of the organization, newest first, one page at a time. Each item has the agent, the daily calling window, the declaration of where the right to call comes from and the statistics of its contacts. The contacts are not in the list: read them with `GET /campaigns/{campaign_id}/contacts`. Required scope: `campaigns: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/campaigns/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

- `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 CampaignsGetResponsesContentApplicationJsonSchemaDataItems, 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_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.

- `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

### CampaignsGetResponsesContentApplicationJsonSchemaDataItems

- `object` ("campaign", required) — Always `campaign`.
- `id` (string, required) — Id of the campaign: use it in `GET /campaigns/{campaign_id}` and in the other campaign operations.
- `name` (string, required) — The name given to the campaign.
- `status` (enum, required) — `draft`: created and not started yet. `running`: the campaign is calling its contacts. `paused`: stopped, it can be started again with `POST /campaigns/{campaign_id}/start`. `completed`: finished, it cannot be started or paused again. `simulated`: only with a test key, nothing was changed.
  - Allowed values: `draft`, `running`, `paused`, `completed`, `simulated`
- `paused_reason` (enum, required) — Set when the platform, and not you, paused the campaign; `null` otherwise. `feature_not_available`: the platform paused the campaign because the plan no longer includes outbound campaigns. `agent_suspended`: the agent was suspended; resuming it restarts the campaign.
  - Allowed values: `feature_not_available`, `agent_suspended`
- `agent` (CampaignsGetResponsesContentApplicationJsonSchemaDataItemsAgent, required) — The agent that makes the calls of the campaign.
- `max_concurrency` (integer, required) — Calls the campaign can make at the same time. The plan limit of concurrent calls still applies.
- `calling_hours` (CampaignsGetResponsesContentApplicationJsonSchemaDataItemsCallingHours, required) — The daily window of the campaign. The effective window is its intersection with the organization window.
- `contact_origin` (CampaignsGetResponsesContentApplicationJsonSchemaDataItemsContactOrigin, required, nullable) — The declaration made when the campaign was created; `null` for a campaign created in the app without one (it cannot be started through the API).
- `stats` (CampaignsGetResponsesContentApplicationJsonSchemaDataItemsStats, required) — Counts of the contacts of the campaign, updated as the calls proceed.
- `simulated` (boolean, required) — `true` with a test key: the operation was only checked and nothing was changed. After `POST /campaigns` with a test key the id does not exist.
- `created_at` (datetime, required) — When the campaign was created, ISO 8601 UTC.

### CampaignsGetResponsesContentApplicationJsonSchemaDataItemsAgent

The agent that makes the calls of the campaign.

- `id` (string, required) — Id of the agent that makes the calls.
- `name` (string, required, nullable) — Name of the agent.

### CampaignsGetResponsesContentApplicationJsonSchemaDataItemsCallingHours

The daily window of the campaign. The effective window is its intersection with the organization window.

- `start` (string, required) — When calls may start each day, HH:MM in Italian time.
- `end` (string, required) — When calls stop each day, HH:MM in Italian time.

### CampaignsGetResponsesContentApplicationJsonSchemaDataItemsContactOrigin

The declaration made when the campaign was created; `null` for a campaign created in the app without one (it cannot be started through the API).

- `basis` (string, required) — Why you declared you may call these people, as sent when the campaign was created: `contract`, `callback_request`, `consent` or `legitimate_interest`.
- `purpose` (string, required) — What the calls are for, as declared: `service` or `marketing`.
- `reference` (string, required, nullable) — The reference in your own system sent with the declaration; `null` if none was sent.
- `opposition_register_checked_on` (string, required, nullable) — The day (YYYY-MM-DD) you declared the numbers were last checked against the public Register of Oppositions; `null` if none was sent.
- `declared_at` (datetime, required) — When the declaration was recorded, ISO 8601 UTC.

### CampaignsGetResponsesContentApplicationJsonSchemaDataItemsStats

Counts of the contacts of the campaign, updated as the calls proceed.

- `total` (integer, required) — Contacts in the campaign.
- `called` (integer, required) — Contacts being dialed or already dialed: those with status `dialing`, `completed` or `failed`.
- `completed` (integer, required) — Contacts with status `completed`.
- `goal_achieved` (integer, required) — Contacts whose call reached the goal of the agent, according to the evaluation of the call.

## Examples

**Response**

```json
{
  "data": [
    {
      "object": "campaign",
      "id": "4e7a9c12-8b3d-4f60-a5e1-6d2c0b9f3a71",
      "name": "Appointment reminders November",
      "status": "running",
      "paused_reason": null,
      "agent": {
        "id": "promemoria-studio-rossi",
        "name": "Promemoria Studio Rossi"
      },
      "max_concurrency": 2,
      "calling_hours": {
        "start": "09:00",
        "end": "18:00"
      },
      "contact_origin": {
        "basis": "contract",
        "purpose": "service",
        "reference": "reminders-2026-11",
        "opposition_register_checked_on": null,
        "declared_at": "2026-11-16T08:55:12Z"
      },
      "stats": {
        "total": 240,
        "called": 96,
        "completed": 88,
        "goal_achieved": 61
      },
      "simulated": false,
      "created_at": "2026-11-16T08:55:12Z"
    },
    {
      "object": "campaign",
      "id": "b83d5f07-2c19-4a6e-9d4b-7e1f0a8c5d23",
      "name": "Satisfaction survey",
      "status": "draft",
      "paused_reason": null,
      "agent": {
        "id": "promemoria-studio-rossi",
        "name": "Promemoria Studio Rossi"
      },
      "max_concurrency": 1,
      "calling_hours": {
        "start": "09:00",
        "end": "18:00"
      },
      "contact_origin": {
        "basis": "contract",
        "purpose": "service",
        "reference": null,
        "opposition_register_checked_on": null,
        "declared_at": "2026-11-16T08:55:12Z"
      },
      "stats": {
        "total": 0,
        "called": 0,
        "completed": 0,
        "goal_achieved": 0
      },
      "simulated": false,
      "created_at": "2026-11-14T15:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ0IjoiMjAyNi0xMS0xNFQxNTozMDowMFoiLCJpZCI6ImI4M2Q1ZjA3In0"
}
```

**SDK Code**

```python
import requests

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

querystring = {"limit":"2"}

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

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

print(response.json())
```

```javascript
const url = 'https://api.getvoxai.com/v1/campaigns?limit=2';
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/campaigns?limit=2"

	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/campaigns?limit=2")

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/campaigns?limit=2")
  .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/campaigns?limit=2', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.getvoxai.com/v1/campaigns?limit=2");
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/campaigns?limit=2")! 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()
```