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

# Fetching Campaigns

> Query and filter campaigns across all connected ad platforms.

The `GET /v1/campaigns` endpoint returns campaigns from all connected platforms in a unified format. You can filter by platform, status, and paginate through results using cursors.

## Basic Request

```bash theme={null}
curl -X GET "https://api.adrelay.dev/v1/campaigns" \
  -H "X-API-Key: $ADRELAY_API_KEY"
```

## Query Parameters

| Parameter  | Type    | Default | Description                                                |
| ---------- | ------- | ------- | ---------------------------------------------------------- |
| `platform` | string  | all     | Filter by platform: `google_ads`, `meta_ads`, `tiktok_ads` |
| `status`   | string  | all     | Filter by status: `ACTIVE`, `PAUSED`, `REMOVED`, `ENDED`   |
| `limit`    | integer | 25      | Number of results per page (max 100)                       |
| `cursor`   | string  | --      | Cursor for the next page of results                        |

## Filtering by Platform

Fetch only Google Ads campaigns:

```bash theme={null}
curl -X GET "https://api.adrelay.dev/v1/campaigns?platform=google_ads" \
  -H "X-API-Key: $ADRELAY_API_KEY"
```

## Filtering by Status

Fetch only active campaigns across all platforms:

```bash theme={null}
curl -X GET "https://api.adrelay.dev/v1/campaigns?status=ACTIVE" \
  -H "X-API-Key: $ADRELAY_API_KEY"
```

Combine filters:

```bash theme={null}
curl -X GET "https://api.adrelay.dev/v1/campaigns?platform=meta_ads&status=PAUSED" \
  -H "X-API-Key: $ADRELAY_API_KEY"
```

## Cursor Pagination

AdRelay uses cursor-based pagination. Each response includes a `pagination` object indicating whether more results are available and providing a cursor for the next page.

### Response Shape

```json theme={null}
{
  "unified": [
    {
      "id": "camp_abc123",
      "platform": "google_ads",
      "remote_id": "123456789",
      "name": "Summer Sale 2026",
      "status": "ACTIVE",
      "goal": "CONVERSIONS",
      "budget_amount": 50.00,
      "budget_period": "DAILY",
      "currency": "USD",
      "created_at": "2026-03-01T12:00:00Z",
      "updated_at": "2026-03-15T08:30:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6ImNhbXBfYWJjMTIzIn0=",
    "has_more": true
  }
}
```

### Paginating Through Results

To fetch the next page, pass the `next_cursor` value as the `cursor` query parameter:

```bash theme={null}
curl -X GET "https://api.adrelay.dev/v1/campaigns?cursor=eyJpZCI6ImNhbXBfYWJjMTIzIn0=" \
  -H "X-API-Key: $ADRELAY_API_KEY"
```

When `has_more` is `false`, you have reached the last page.

### Full Pagination Example (Node.js)

```javascript theme={null}
async function getAllCampaigns() {
  const campaigns = [];
  let cursor = null;

  do {
    const url = new URL("https://api.adrelay.dev/v1/campaigns");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);

    const response = await fetch(url.toString(), {
      headers: { "X-API-Key": process.env.ADRELAY_API_KEY },
    });

    const data = await response.json();
    campaigns.push(...data.unified);

    cursor = data.pagination.has_more ? data.pagination.next_cursor : null;
  } while (cursor);

  return campaigns;
}
```

## Campaign Object Fields

| Field           | Type   | Description                                                      |
| --------------- | ------ | ---------------------------------------------------------------- |
| `id`            | string | AdRelay's unique identifier for the campaign                     |
| `platform`      | string | Source platform (`google_ads`, `meta_ads`, `tiktok_ads`)         |
| `remote_id`     | string | The campaign ID on the original platform                         |
| `name`          | string | Campaign name                                                    |
| `status`        | string | `ACTIVE`, `PAUSED`, `REMOVED`, or `ENDED`                        |
| `goal`          | string | Campaign objective (e.g., `CONVERSIONS`, `AWARENESS`, `TRAFFIC`) |
| `budget_amount` | number | Budget amount in the campaign's currency                         |
| `budget_period` | string | `DAILY` or `LIFETIME`                                            |
| `currency`      | string | ISO 4217 currency code                                           |
| `created_at`    | string | ISO 8601 timestamp                                               |
| `updated_at`    | string | ISO 8601 timestamp                                               |