> ## Documentation Index
> Fetch the complete documentation index at: https://doc.convo.co.in/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /project/{project_id}/campaigns — List Campaigns

> POST /project/{project_id}/campaigns — Retrieve a list of API, Broadcast, or all campaigns in your project with pagination support.

Retrieve a paginated list of campaigns in your project. You can filter by campaign type — `API`, `BROADCAST`, or `ALL` — and paginate through results using `skip` and `limit`.

<Note>
  This endpoint uses **POST** (not GET) so that filter criteria can be passed in the request body rather than as query parameters.
</Note>

## Endpoint

```text theme={null}
POST https://connect.api-wa.co/project-apis/v1/project/{project_id}/campaigns
```

## Authentication

```text theme={null}
X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD
```

## Path Parameters

<ParamField path="project_id" type="string" required>
  Your Convo project ID.
</ParamField>

## Request Body

<ParamField body="campaignType" type="string" required>
  The type of campaigns to retrieve. Accepted values:

  * `"API"` — Returns only API campaigns (created programmatically via the Create Campaign endpoint).
  * `"BROADCAST"` — Returns only broadcast campaigns (created in the Convo dashboard).
  * `"ALL"` — Returns both API and broadcast campaigns.
</ParamField>

<ParamField body="skip" type="integer">
  The number of records to skip before returning results. Use with `limit` to paginate through large lists. Defaults to `0`.
</ParamField>

<ParamField body="limit" type="integer">
  The maximum number of campaigns to return. Defaults to `10`. Must be a positive integer.
</ParamField>

## Request Example

```bash theme={null}
curl -X POST "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/campaigns" \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignType": "API",
    "skip": 0,
    "limit": 10
  }'
```

To fetch the next page:

```bash theme={null}
curl -X POST "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/campaigns" \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignType": "API",
    "skip": 10,
    "limit": 10
  }'
```

## Response

A successful request returns `200 OK` with a `campaigns` array.

```json theme={null}
{
  "campaigns": [
    {
      "_id": "64b3e1ac7f2c0a001d8e9f34",
      "name": "ShipmentAlerts_Q4_2024",
      "type": "API",
      "status": "LIVE",
      "message_type": "TEXT",
      "message_payload": {
        "template": {
          "_id": "64a1f3bc9e4a2b001c3d7f12",
          "name": "shipping_update_v1",
          "label": "Shipping Update",
          "status": "APPROVED",
          "category": "TRANSACTIONAL",
          "type": "TEXT",
          "language": "English",
          "text": "Hi {{1}}, your order {{2}} has been shipped and will arrive by {{3}}.",
          "total_parameters": 3
        }
      },
      "audience_size": 0,
      "submitted": 1482,
      "project_id": "YOUR_PROJECT_ID",
      "created_at": "2024-07-16T09:30:00.000Z"
    },
    {
      "_id": "64c2d4ff1a3b0b002e7f0a55",
      "name": "InvoiceDelivery_2024",
      "type": "API",
      "status": "LIVE",
      "message_type": "FILE",
      "message_payload": {
        "template": {
          "_id": "64b0c1aa3e2d1c001f4a8b99",
          "name": "invoice_delivery_v1",
          "label": "Invoice Delivery",
          "status": "APPROVED",
          "category": "TRANSACTIONAL",
          "type": "FILE",
          "language": "English",
          "text": "Hi {{1}}, please find your invoice {{2}} for ₹{{3}} attached.",
          "total_parameters": 3
        }
      },
      "audience_size": 0,
      "submitted": 374,
      "project_id": "YOUR_PROJECT_ID",
      "created_at": "2024-08-02T14:15:00.000Z"
    }
  ]
}
```

### Campaign Object Fields

| Field                      | Type    | Description                                                                                          |
| -------------------------- | ------- | ---------------------------------------------------------------------------------------------------- |
| `_id`                      | string  | Unique campaign identifier.                                                                          |
| `name`                     | string  | Campaign name.                                                                                       |
| `type`                     | string  | `"API"` or `"BROADCAST"`.                                                                            |
| `status`                   | string  | `"LIVE"`, `"PAUSED"`, or `"STOPPED"`.                                                                |
| `message_type`             | string  | Media type of the linked template.                                                                   |
| `message_payload.template` | object  | The linked WhatsApp template object.                                                                 |
| `audience_size`            | integer | Number of contacts in the campaign audience (0 for API campaigns — audience is determined per-send). |
| `submitted`                | integer | Total number of messages sent through this campaign so far.                                          |
| `project_id`               | string  | The project this campaign belongs to.                                                                |
| `created_at`               | string  | ISO 8601 creation timestamp.                                                                         |

## Error Responses

| Status                      | Description                                                                                                        |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `400 Bad Request`           | `campaignType` is missing or not one of `"API"`, `"BROADCAST"`, `"ALL"`. `limit` or `skip` is not a valid integer. |
| `500 Internal Server Error` | An unexpected server-side error occurred.                                                                          |

```json theme={null}
{
  "error": "Bad Request",
  "message": "campaignType must be one of: API, BROADCAST, ALL."
}
```