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

# Retrieve Campaign Audience and Delivery Status Data

> List campaign recipients with their delivery status, filtered by category (SENT, READ, FAILED) and paginated with cursor-based navigation.

Use this endpoint to retrieve the full list of recipients for a specific campaign, along with their delivery status. You can filter results by delivery category (e.g., `READ`, `DELIVERED`, `FAILED`) and paginate through large audiences using cursor-based pagination.

## Endpoint

```text theme={null}
GET https://connect.api-wa.co/project-apis/v1/project/{project_id}/campaign/audience/{campaign_id}
```

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

<ParamField path="campaign_id" type="string" required>
  The unique ID of the campaign whose audience you want to retrieve.
</ParamField>

## Query Parameters

<ParamField query="limit" type="string">
  Number of results to return per page. Defaults to `20`. Maximum is `1000`.
</ParamField>

<ParamField query="sort" type="string">
  Sort order for results. Accepts `"asc"` (ascending) or `"desc"` (descending). Defaults to `"asc"`.
</ParamField>

<ParamField query="after" type="string">
  Cursor for fetching the next page of results. Use the value from `response.paging.cursors.after`.
</ParamField>

<ParamField query="before" type="string">
  Cursor for fetching the previous page of results. Use the value from `response.paging.cursors.before`.
</ParamField>

<ParamField query="category" type="string">
  Filter recipients by their message delivery status. Accepted values:

  * `SENT` — Message was sent
  * `DELIVERED` — Message was delivered to the device
  * `READ` — Message was opened by the recipient
  * `FAILED` — Message failed to deliver
  * `REPLIED` — Recipient replied to the campaign
  * `CLICKED` — Recipient clicked a button or link in the message
</ParamField>

<ParamField query="fields" type="string">
  Comma-separated list of field names to include in the response. Omit to return all fields.
</ParamField>

<ParamField query="startDate" type="string">
  ISO 8601 date-time string. Filters audience records updated on or after this date.
</ParamField>

<ParamField query="endDate" type="string">
  ISO 8601 date-time string. Filters audience records updated on or before this date.
</ParamField>

## Request Example

Fetch the first 100 recipients who have **read** the campaign message:

```bash theme={null}
curl "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/campaign/audience/64b3e1ac7f2c0a001d8e9f34?category=READ&limit=100" \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD"
```

## Response

<ResponseField name="total" type="integer">
  The total number of recipients matching the query (across all pages).
</ResponseField>

<ResponseField name="data" type="array">
  Array of recipient objects. Each object contains:

  <Expandable title="Recipient Object">
    <ResponseField name="_id" type="string">
      Unique internal ID for this audience record.
    </ResponseField>

    <ResponseField name="userNumber" type="string">
      The recipient's WhatsApp phone number in international format (e.g., `"919498526285"`).
    </ResponseField>

    <ResponseField name="sentAt" type="string">
      ISO 8601 timestamp of when the message was sent to this recipient.
    </ResponseField>

    <ResponseField name="userName" type="string">
      Display name of the recipient contact.
    </ResponseField>

    <ResponseField name="deliveredAt" type="string">
      ISO 8601 timestamp of when the message was delivered. Present only if delivered.
    </ResponseField>

    <ResponseField name="readAt" type="string">
      ISO 8601 timestamp of when the message was read. Present only if read.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="paging" type="object">
  Pagination metadata for navigating through large result sets.

  <Expandable title="Paging Object">
    <ResponseField name="cursors.after" type="string">
      Pass this value as the `after` query parameter to fetch the next page of results.
    </ResponseField>

    <ResponseField name="cursors.before" type="string">
      Pass this value as the `before` query parameter to fetch the previous page of results.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Response

```json theme={null}
{
  "total": 3,
  "data": [
    {
      "_id": "629f8041b45cc338a0a082bc",
      "userNumber": "919498526285",
      "sentAt": "2024-01-07T16:43:41.331Z",
      "userName": "Priya"
    },
    {
      "_id": "629f8041b45cc338a0a08130",
      "userNumber": "919149327854",
      "sentAt": "2024-01-07T16:43:41.332Z",
      "userName": "Mohit"
    }
  ],
  "paging": {
    "cursors": {
      "after": "NjI5ZjgwNDJiNDVjYzMzOGEwYTA4NDFm...",
      "before": "NjI5ZjgwNDFiNDVjYzMzOGEwYTA4MmJj..."
    }
  }
}
```

## Cursor Pagination

This endpoint uses **cursor-based pagination** to efficiently iterate through large audiences.

1. Make an initial request without `after` or `before` to get the first page.
2. If there are more results, the response includes a `paging.cursors.after` value.
3. Pass that value as the `after` query parameter in your next request to retrieve the following page.
4. Repeat until `paging.cursors.after` is no longer present in the response, indicating you have reached the last page.

Use `before` to navigate backwards through pages.