> ## Documentation Index
> Fetch the complete documentation index at: https://convo.co.in/docs/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.

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

**project\_id** `string` *required*

Your Convo project ID.

## Request Body

**campaignType** `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.

**skip** `integer`

The number of records to skip before returning results. Use with `limit` to paginate through large lists. Defaults to `0`.

**limit** `integer`

The maximum number of campaigns to return. Defaults to `10`. Must be a positive integer.

## 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."
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.