> ## Documentation Index > Fetch the complete documentation index at: https://docs.unleashx.ai/llms.txt > Use this file to discover all available pages before exploring further. # List Campaigns > Retrieve a paginated list of campaigns with optional filters. Use this endpoint to **retrieve a paginated list of campaigns** with optional filters. ## API Endpoint **GET** `/api/v1/global/campaign-list` **Base URL:** `https://www.tryunleashx.com` **Authentication:** Required (Token header: `token` or `api_access_token`) ## Query Parameters | Parameter | Type | Required | Description | | ----------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page` | integer | No | Page number (default: `1`) | | `limit` | integer | No | Records per page (default: `10`) | | `agent_id` | integer \| array | No | Filter by agent ID(s). Accepts `5` or a JSON array `[5,9]` | | `campaign_name` | string | No | Partial name search (LIKE) | | `campaign_status` | string \| array | No | Filter by status. Valid values: `draft`, `inprogress`, `hold`, `pause`, `force_completed`, `deleted`. Accepts a JSON array such as `["draft","inprogress"]`. Defaults to all except `deleted`. | | `workspace_id` | integer \| array | No | Workspace scope override. Accepts a single id (`293`) or a JSON array (`[293,294]`). When omitted, only the token's own workspace is listed. | ### Workspace Scope By default the list is scoped to the workspace the API token belongs to. Passing `workspace_id` overrides that, which is how a company-level token reads another workspace's campaigns: * `?workspace_id=293` — campaigns of workspace 293 only * `?workspace_id=[293,294]` — campaigns of both workspaces The scope is always restricted to the token's own company, so a `workspace_id` belonging to another company returns no records. Use [List Workspaces](/api-reference/workspaces/workspace-list) to discover the ids you can pass here. ## Campaign Status Values | Status | Numeric value | Description | | ----------------- | ------------- | ---------------------------- | | `draft` | `0` | Campaign is in draft mode | | `inprogress` | `1` | Campaign is actively running | | `hold` | `2` | Campaign is on hold | | `pause` | `3` | Campaign is paused | | `force_completed` | `4` | Campaign was force completed | | `deleted` | `5` | Campaign has been deleted | ## Success Response **Status Code:** `200 OK` ```json theme={null} { "error": false, "code": 200, "message": "", "timestamp": 1769243432947, "data": { "campaigns": [ { "id": 42, "campaign_name": "Winter Sale Campaign", "is_published": 1, "is_legacy": 0, "agent_id": 18, "agent_name": "Sales Agent", "workspace_id": 293, "workspace_name": "Growth Team", "start_end_date": "1 Dec - 31 Dec", "max_retry": 3, "max_delay": "5m - 30m", "total_audience": 500, "progress": "120/500", "has_audience": true, "has_fresh_inqueue_audience": true, "campaign_status_name": "Inprogress", "campaign_status": 1, "last_updated": "2 days ago" } ], "pagination": { "totalRecords": 25, "totalPages": 3, "currentPage": 1, "limit": 10 } } } ``` ## Response Fields ### Campaign Object | Field | Type | Description | | ---------------------------- | -------------- | ---------------------------------------------------------------------------------- | | `id` | integer | Campaign ID | | `campaign_name` | string | Campaign name | | `is_published` | integer | `1` when the campaign has been published | | `is_legacy` | integer | `1` when the campaign uses the legacy audience model | | `agent_id` | integer | ID of the voice agent running the campaign | | `agent_name` | string | Name of the voice agent | | `workspace_id` | integer | Workspace the campaign belongs to | | `workspace_name` | string | Workspace name | | `start_end_date` | string or null | Schedule window, e.g. `"1 Dec - 31 Dec"` | | `max_retry` | integer | Configured re-attempts | | `max_delay` | string or null | Delay / condition between attempts | | `total_audience` | integer | Contacts connected to the campaign | | `progress` | string | Formatted as `called/total` | | `has_audience` | boolean | `true` when the campaign has any audience | | `has_fresh_inqueue_audience` | boolean | `true` when contacts are still waiting to be dialed | | `campaign_status_name` | string | Human-readable status (see table above), or `Completed` when `end_date` has passed | | `campaign_status` | integer | Numeric status value | | `last_updated` | string or null | Relative last-modified time, e.g. `"2 days ago"` | ### Pagination Object | Field | Type | Description | | -------------- | ------- | ---------------------------------- | | `totalRecords` | integer | Total number of matching campaigns | | `totalPages` | integer | Total number of pages | | `currentPage` | integer | Current page number | | `limit` | integer | Records per page | ## Notes * `campaign_status` defaults to all statuses except `deleted`. * A campaign is automatically labeled **Completed** in `campaign_status_name` if its `end_date` has passed. The numeric `campaign_status` is unchanged. * `progress` is formatted as `called/total` audience count. * `workspace_id` / `workspace_name` are returned only for API-token (global) requests. * Results are ordered by creation date, newest first. ## Example cURL ### Campaigns of the token's own workspace ```bash theme={null} curl -X GET "https://www.tryunleashx.com/api/v1/global/campaign-list?page=1&limit=10&campaign_status=inprogress" \ -H "token: " ``` ### Campaigns of a specific workspace ```bash theme={null} curl -X GET "https://www.tryunleashx.com/api/v1/global/campaign-list?workspace_id=293" \ -H "token: " ``` ### Campaigns across multiple workspaces ```bash theme={null} curl -X GET "https://www.tryunleashx.com/api/v1/global/campaign-list?workspace_id=[293,294]&limit=50" \ -H "token: " ``` ## OpenAPI ````yaml api-reference/openapi.json GET /campaign-list openapi: 3.1.0 info: title: >- UnleashX - Build human like conversations | Voice Agents | Automations | AI Workforce version: 1.0.0 description: UnleashX - Your home for human like conversations servers: - url: https://www.tryunleashx.com/api/v1/global/ security: - bearerAuth: [] paths: /campaign-list: get: tags: - Campaigns summary: List campaigns description: Retrieve a paginated list of campaigns with optional filters. parameters: - name: token in: header required: true description: API token for authentication schema: type: string - name: page in: query required: false schema: type: integer description: 'Page number (default: 1)' - name: limit in: query required: false schema: type: integer description: 'Records per page (default: 10)' - name: agent_id in: query required: false schema: type: integer description: Filter by agent ID - name: campaign_name in: query required: false schema: type: string description: Partial name search (LIKE) - name: campaign_status in: query required: false schema: type: string enum: - draft - inprogress - hold - pause - force_completed - deleted description: >- Filter by status. Accepts a single value or a JSON array such as ["draft","inprogress"]. Defaults to all except deleted. - name: workspace_id in: query required: false schema: type: string description: >- Workspace scope override. Accepts a single id (293), a JSON array ([293,294]) or a comma-free JSON string. When omitted the token's own workspace is used. Always restricted to the token's company. responses: '200': description: Campaign list retrieved successfully content: application/json: schema: type: object properties: campaigns: type: array items: type: object properties: id: type: integer campaign_name: type: string is_published: type: integer is_legacy: type: integer description: 1 when the campaign uses the legacy audience model agent_id: type: integer agent_name: type: string workspace_id: type: integer description: Workspace the campaign belongs to workspace_name: type: string start_end_date: type: string nullable: true description: Schedule window, e.g. "1 Dec - 31 Dec" max_retry: type: integer max_delay: type: string nullable: true total_audience: type: integer description: Contacts connected to the campaign progress: type: string description: Formatted as called/total has_audience: type: boolean has_fresh_inqueue_audience: type: boolean campaign_status_name: type: string description: >- Draft, Inprogress, Hold, Pause, Force Completed, Deleted, or Completed when end_date has passed campaign_status: type: integer description: >- Numeric status: 0 draft, 1 inprogress, 2 hold, 3 pause, 4 force_completed, 5 deleted last_updated: type: string nullable: true pagination: type: object properties: totalRecords: type: integer totalPages: type: integer currentPage: type: integer limit: type: integer '400': description: Bad Request '401': description: Unauthorized security: [] components: securitySchemes: bearerAuth: type: http scheme: bearer ````