> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talkover.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Campaigns

> Retrieve a list of all campaigns with filtering and pagination options

# List Campaigns

Retrieve a list of all campaigns for the authenticated environment with various filtering options and pagination support.

## Endpoint

```
GET /api/v1/campaigns
```

## Request headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer talq_your_environment_token_here`
</ParamField>

## Query parameters

<ParamField query="status" type="string" required={false}>
  Filter by campaign status. Options: `draft`, `active`, `paused`, `completed`, `cancelled`
</ParamField>

<ParamField query="campaign_type" type="string" required={false}>
  Filter by campaign type. Options: `sales`, `follow_up`, `reminder`, `custom`
</ParamField>

<ParamField query="agent_id" type="string" required={false}>
  Filter by agent ID
</ParamField>

<ParamField query="date_from" type="string" required={false}>
  Filter campaigns from date (YYYY-MM-DD)
</ParamField>

<ParamField query="date_to" type="string" required={false}>
  Filter campaigns to date (YYYY-MM-DD)
</ParamField>

<ParamField query="search" type="string" required={false}>
  Search in campaign name or description
</ParamField>

<ParamField query="per_page" type="integer" required={false}>
  Number of items per page (default: 20, max: 100)
</ParamField>

<ParamField query="page" type="integer" required={false}>
  Page number (default: 1)
</ParamField>

## Example requests

<RequestExample>
  ```bash theme={null}
  # Request 1: Get all campaigns
  curl -X GET "https://app.talkover.ai/api/v1/campaigns" \
    -H "Authorization: Bearer talq_your_environment_token_here"
  ```

  ```javascript theme={null}
  // Request 1: Get all campaigns
  const response = await fetch('https://app.talkover.ai/api/v1/campaigns', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here'
    }
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

<RequestExample>
  ```bash theme={null}
  # Request 2: Get active sales campaigns
  curl -X GET "https://app.talkover.ai/api/v1/campaigns?status=active&campaign_type=sales&per_page=50" \
    -H "Authorization: Bearer talq_your_environment_token_here"
  ```

  ```javascript theme={null}
  // Request 2: Get active sales campaigns
  const response = await fetch('https://app.talkover.ai/api/v1/campaigns?status=active&campaign_type=sales&per_page=50', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here'
    }
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

<RequestExample>
  ```bash theme={null}
  # Request 3: Search for specific campaign
  curl -X GET "https://app.talkover.ai/api/v1/campaigns?search=Sales Campaign&agent_id=agent-uuid-1" \
    -H "Authorization: Bearer talq_your_environment_token_here"
  ```

  ```javascript theme={null}
  // Request 3: Search for specific campaign
  const response = await fetch('https://app.talkover.ai/api/v1/campaigns?search=Sales Campaign&agent_id=agent-uuid-1', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here'
    }
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

## Response

### Success Response (200 OK)

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "campaign-uuid-1",
        "name": "Sales Campaign",
        "description": "Outbound sales campaign for Q1",
        "status": "active",
        "campaign_type": "sales",
        "start_date": "2024-01-01",
        "days_of_week": [1, 2, 3, 4, 5],
        "earliest_call_time": "09:00:00",
        "latest_call_time": "17:00:00",
        "timezone": "America/New_York",
        "agent_id": "agent-uuid-1",
        "initial_call_delay": 0,
        "max_retries": 3,
        "retry_cooldown_hours": 24,
        "agent": {
          "id": "agent-uuid-1",
          "name": "Sales Agent",
          "label": "Sales Agent Label"
        },
        "stats": {
          "total_calls": 100,
          "completed_calls": 80,
          "failed_calls": 20,
          "success_rate": 80.0
        },
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      },
      {
        "id": "campaign-uuid-2",
        "name": "Follow-up Campaign",
        "description": "Follow-up calls for existing customers",
        "status": "paused",
        "campaign_type": "follow_up",
        "start_date": "2024-01-15",
        "days_of_week": [2, 3, 4],
        "earliest_call_time": "10:00:00",
        "latest_call_time": "16:00:00",
        "timezone": "America/New_York",
        "agent_id": "agent-uuid-2",
        "initial_call_delay": 0,
        "max_retries": 2,
        "retry_cooldown_hours": 48,
        "agent": {
          "id": "agent-uuid-2",
          "name": "Support Agent",
          "label": "Support Agent Label"
        },
        "stats": {
          "total_calls": 50,
          "completed_calls": 35,
          "failed_calls": 15,
          "success_rate": 70.0
        },
        "created_at": "2024-01-15T00:00:00Z",
        "updated_at": "2024-01-15T00:00:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "last_page": 5,
      "per_page": 20,
      "total": 100,
      "from": 1,
      "to": 20
    }
  }
  ```
</ResponseExample>

### Response fields

<ResponseField name="success" type="boolean" required>
  Indicates if the operation was successful.
</ResponseField>

<ResponseField name="data" type="array" required>
  Array of campaign objects.

  <Expandable title="Campaign Object">
    <ResponseField name="id" type="string" required>
      Unique identifier for the campaign.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Name of the campaign.
    </ResponseField>

    <ResponseField name="description" type="string">
      Description of the campaign.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Current status of the campaign. Options: `draft`, `active`, `paused`, `completed`, `cancelled`.
    </ResponseField>

    <ResponseField name="campaign_type" type="string" required>
      Type of campaign. Options: `sales`, `follow_up`, `reminder`, `custom`.
    </ResponseField>

    <ResponseField name="start_date" type="string" required>
      Campaign start date (YYYY-MM-DD).
    </ResponseField>

    <ResponseField name="days_of_week" type="array" required>
      Array of days when calls can be made (1=Monday, 7=Sunday).
    </ResponseField>

    <ResponseField name="earliest_call_time" type="string" required>
      Earliest time to make calls (HH:MM:SS).
    </ResponseField>

    <ResponseField name="latest_call_time" type="string" required>
      Latest time to make calls (HH:MM:SS).
    </ResponseField>

    <ResponseField name="timezone" type="string" required>
      Timezone for call scheduling.
    </ResponseField>

    <ResponseField name="agent_id" type="string" required>
      UUID of the agent assigned to the campaign.
    </ResponseField>

    <ResponseField name="initial_call_delay" type="integer" required>
      Initial delay before making calls (seconds).
    </ResponseField>

    <ResponseField name="max_retries" type="integer" required>
      Maximum number of retry attempts.
    </ResponseField>

    <ResponseField name="retry_cooldown_hours" type="integer" required>
      Hours to wait between retry attempts.
    </ResponseField>

    <ResponseField name="agent" type="object" required>
      Agent information assigned to the campaign.

      <Expandable title="Agent Object">
        <ResponseField name="id" type="string" required>
          Unique identifier for the agent.
        </ResponseField>

        <ResponseField name="name" type="string" required>
          Name of the agent.
        </ResponseField>

        <ResponseField name="label" type="string" required>
          Display label for the agent.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="stats" type="object" required>
      Campaign statistics.

      <Expandable title="Stats Object">
        <ResponseField name="total_calls" type="integer" required>
          Total number of calls in the campaign.
        </ResponseField>

        <ResponseField name="completed_calls" type="integer" required>
          Number of successfully completed calls.
        </ResponseField>

        <ResponseField name="failed_calls" type="integer" required>
          Number of failed calls.
        </ResponseField>

        <ResponseField name="success_rate" type="number" required>
          Success rate percentage.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      ISO 8601 timestamp when the campaign was created.
    </ResponseField>

    <ResponseField name="updated_at" type="string" required>
      ISO 8601 timestamp when the campaign was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object" required>
  Pagination metadata.

  <Expandable title="Pagination Object">
    <ResponseField name="current_page" type="integer" required>
      Current page number.
    </ResponseField>

    <ResponseField name="last_page" type="integer" required>
      Last page number.
    </ResponseField>

    <ResponseField name="per_page" type="integer" required>
      Number of items per page.
    </ResponseField>

    <ResponseField name="total" type="integer" required>
      Total number of items.
    </ResponseField>

    <ResponseField name="from" type="integer" required>
      Starting item number for current page.
    </ResponseField>

    <ResponseField name="to" type="integer" required>
      Ending item number for current page.
    </ResponseField>
  </Expandable>
</ResponseField>

## Error responses

### 401 Unauthorized

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Unauthorized"
  }
  ```
</ResponseExample>

### 422 Validation Error

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "The given data was invalid.",
    "errors": {
      "status": [
        "The selected status is invalid."
      ],
      "campaign_type": [
        "The selected campaign type is invalid."
      ],
      "date_from": [
        "The date from must be a valid date."
      ]
    }
  }
  ```
</ResponseExample>

### 500 Server Error

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Internal server error."
  }
  ```
</ResponseExample>

## Error codes

| Code               | Description                                | HTTP Status |
| ------------------ | ------------------------------------------ | ----------- |
| `INVALID_TOKEN`    | Authentication token is invalid or missing | 401         |
| `VALIDATION_ERROR` | Query parameter validation failed          | 422         |
| `SERVER_ERROR`     | Internal server error occurred             | 500         |

## Important notes

<Info>
  **Pagination support.** All list endpoints support pagination with `page` and `per_page` parameters.
</Info>

<Info>
  **Date filtering.** Use `date_from` and `date_to` to filter campaigns by date range.
</Info>

<Info>
  **Search functionality.** The search parameter searches in campaign names and descriptions.
</Info>

<Info>
  **Statistics included.** Each campaign includes real-time statistics about call performance.
</Info>

## Related endpoints

* **Create Campaign**: `POST /api/v1/campaigns`
* **Get Campaign**: `GET /api/v1/campaigns/{campaign_id}`
* **Update Campaign**: `PUT /api/v1/campaigns/{campaign_id}`
* **List Calls**: `GET /api/v1/calls`