List campaigns

GET /api/v1/campaign

Return one page of your organization's campaigns, newest-first. By default only live (non-archived) campaigns are returned. Each item carries the full campaign response plus per-campaign outcome mini-stats for a list table.

Paginated envelope

This endpoint returns a paginated envelope { items, total, page, limit } — read the campaign array from items.

Query parameters

Parameter	Type	Default	Notes
`page`	int (≥ 1)	`1`	Page number.
`limit`	int (1..100)	`25`	Campaigns per page.
`state`	string	—	Filter to a single lifecycle state: `created`, `syncing`, `running`, `paused`, `completed`, `failed`. An unknown value is a `422`.
`archived`	bool	`false`	`false` lists live campaigns only; `true` lists only archived campaigns.

total counts all campaigns matching the same filters (before pagination), so you can render page controls.

Response

{
  "items": [
    {
      "id":   7,
      "name": "Q3 outreach",
      "state": "running",
      "agent_id":      42,
      "agent_name":    "Sales bot",
      "source_type":   "csv",
      "source_id":     "campaigns/1/abc123_contacts.csv",
      "telephony_configuration_id":   3,
      "telephony_configuration_name": "Twilio · main",
      "total_rows":     500,
      "processed_rows": 120,
      "failed_rows":     25,
      "max_concurrency": 5,
      "retry_config":      { /* ... */ },
      "schedule_config":   { /* ... */ },
      "circuit_breaker":   { /* ... */ },
      "executed_count":      120,
      "total_queued_count":  500,
      "connected_count":      88,
      "retrying_count":        6,
      "failed_contact_count":  20,
      "in_flight_count":        3,
      "archived_at":  null,
      "logs":          [ /* structured event entries */ ],
      "created_at":   "2026-07-16T10:00:00Z",
      "started_at":   "2026-07-16T10:05:00Z",
      "completed_at": null
    }
  ],
  "total": 42,
  "page":  1,
  "limit": 25
}

Field	Notes
`state`	`created`, `syncing`, `running`, `paused`, `completed`, `failed` — not `status`.
`agent_id` / `agent_name`	The campaign's target agent (internal integer id and display name).
`source_type`	Always `"csv"` (the only supported source).
`telephony_configuration_id`	Telephony config the campaign dials from. The from-number pool is keyed per `(org, tcid)`.
`total_rows` / `processed_rows` / `failed_rows`	CSV-sync counters. `total_rows` is `null` until the first sync completes.
`executed_count` / `total_queued_count`	Queued-runs registry counters.
`connected_count`	Contact-level count: contacts reached at least once (`completed` or `voicemail`).
`retrying_count`	Contacts with a future retry pending.
`failed_contact_count`	Contacts that finished without ever connecting (a failed/busy/no-answer/canceled outcome, or a dispatch failure).
`in_flight_count`	Contacts with a call in flight (dispatched, awaiting an outcome).
`archived_at`	`null` for live campaigns; an ISO timestamp once archived.
`logs`	Append-only structured event log. See the overview.

Mini-stats are contact-level

connected_count, retrying_count, failed_contact_count, and in_flight_count count contacts (one root + retries chain = one contact), not attempts — a contact retried three times counts once. These four fields are populated only on this list endpoint; the single-campaign endpoints return them as 0.

Examples

# First page of live campaigns
curl "https://dashboard.zoxa.ai/api/v1/campaign?page=1&limit=25" \
  -H "X-API-Key: zsk_..."

# Only running campaigns
curl "https://dashboard.zoxa.ai/api/v1/campaign?state=running" \
  -H "X-API-Key: zsk_..."

# Archived campaigns
curl "https://dashboard.zoxa.ai/api/v1/campaign?archived=true" \
  -H "X-API-Key: zsk_..."

Errors

Status	`detail`	When
`422`	array	`state` is not a valid lifecycle state, or `limit > 100`.

Query parameters

Response

Examples

Errors

On this page