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

# Campaigns

> Retrieve and manage your synced Meta Ads campaigns

# Campaigns

The Campaigns API provides access to your synced Meta Ads campaigns, including their configuration, status, and performance metrics.

***

## List campaigns

<api method="GET" path="/v1/campaigns" />

Retrieve a paginated list of campaigns across all connected ad accounts.

### Query parameters

| Parameter    | Type      | Required | Default | Description                       |
| ------------ | --------- | -------- | ------- | --------------------------------- |
| `account_id` | `string`  | No       | —       | Filter by connected ad account ID |
| `page`       | `integer` | No       | `1`     | Page number                       |
| `page_size`  | `integer` | No       | `20`    | Results per page (max 100)        |

### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.klayrai.com/v1/campaigns?account_id=act_123456789&page_size=10" \
    -H "x-api-key: klyr_live_abc123def456ghi789" \
    -H "klayrai-version: 2026-03-01"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    account_id: "act_123456789",
    page_size: "10",
  });

  const response = await fetch(
    `https://api.klayrai.com/v1/campaigns?${params}`,
    {
      headers: {
        "x-api-key": "klyr_live_abc123def456ghi789",
        "klayrai-version": "2026-03-01",
      },
    }
  );

  const data = await response.json();
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "data": [
    {
      "id": "camp_abc123",
      "metaCampaignId": "23851234567890",
      "accountId": "act_001",
      "name": "Summer Sale 2026 - TOF",
      "status": "ACTIVE",
      "objective": "CONVERSIONS",
      "buyingType": "AUCTION",
      "dailyBudget": 150.00,
      "lifetimeBudget": null,
      "currency": "EUR",
      "bidStrategy": "LOWEST_COST_WITHOUT_CAP",
      "adSetCount": 4,
      "adCount": 12,
      "lastSyncedAt": "2026-03-10T14:00:00Z",
      "createdAt": "2026-02-15T10:00:00Z",
      "updatedAt": "2026-03-10T14:00:00Z",
      "insights": {
        "spend": 2840.50,
        "impressions": 412000,
        "clicks": 8240,
        "conversions": 142,
        "cpa": 20.00,
        "roas": 2.1,
        "ctr": 2.0,
        "cpm": 6.89,
        "dateRange": "last_7d"
      },
      "latestDiagnostic": {
        "id": "diag_8f2k4n6m",
        "riskLevel": "HIGH",
        "issuesDetected": 3,
        "completedAt": "2026-03-10T14:30:08Z"
      }
    },
    {
      "id": "camp_def456",
      "metaCampaignId": "23851234567891",
      "accountId": "act_001",
      "name": "Retargeting - Cart Abandoners",
      "status": "ACTIVE",
      "objective": "CONVERSIONS",
      "buyingType": "AUCTION",
      "dailyBudget": 80.00,
      "lifetimeBudget": null,
      "currency": "EUR",
      "bidStrategy": "COST_CAP",
      "adSetCount": 2,
      "adCount": 6,
      "lastSyncedAt": "2026-03-10T14:00:00Z",
      "createdAt": "2026-02-20T09:00:00Z",
      "updatedAt": "2026-03-10T14:00:00Z",
      "insights": {
        "spend": 560.00,
        "impressions": 95000,
        "clicks": 3800,
        "conversions": 89,
        "cpa": 6.29,
        "roas": 5.8,
        "ctr": 4.0,
        "cpm": 5.89,
        "dateRange": "last_7d"
      },
      "latestDiagnostic": {
        "id": "diag_3j7h9p2q",
        "riskLevel": "HIGH",
        "issuesDetected": 2,
        "completedAt": "2026-03-10T12:15:06Z"
      }
    }
  ],
  "pagination": {
    "total": 12,
    "page": 1,
    "page_size": 10,
    "hasMore": true
  }
}
```

***

## Get campaign detail

<api method="GET" path="/v1/campaigns/{id}" />

Retrieve the full detail of a single campaign, including its ad sets and ads.

### Path parameters

| Parameter | Type     | Required | Description                                   |
| --------- | -------- | -------- | --------------------------------------------- |
| `id`      | `string` | Yes      | The KlayrAI campaign ID (e.g., `camp_abc123`) |

### Query parameters

| Parameter           | Type     | Required | Default   | Description                                                                                       |
| ------------------- | -------- | -------- | --------- | ------------------------------------------------------------------------------------------------- |
| `include`           | `string` | No       | —         | Comma-separated list of related resources to include: `adSets`, `ads`, `diagnostics`, `insights`  |
| `insightsDateRange` | `string` | No       | `last_7d` | Date range for insights data: `today`, `yesterday`, `last_7d`, `last_14d`, `last_30d`, `lifetime` |

### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.klayrai.com/v1/campaigns/camp_abc123?include=adSets,insights&insightsDateRange=last_14d" \
    -H "x-api-key: klyr_live_abc123def456ghi789" \
    -H "klayrai-version: 2026-03-01"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    include: "adSets,insights",
    insightsDateRange: "last_14d",
  });

  const response = await fetch(
    `https://api.klayrai.com/v1/campaigns/camp_abc123?${params}`,
    {
      headers: {
        "x-api-key": "klyr_live_abc123def456ghi789",
        "klayrai-version": "2026-03-01",
      },
    }
  );

  const data = await response.json();
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "data": {
    "id": "camp_abc123",
    "metaCampaignId": "23851234567890",
    "accountId": "act_001",
    "name": "Summer Sale 2026 - TOF",
    "status": "ACTIVE",
    "objective": "CONVERSIONS",
    "buyingType": "AUCTION",
    "dailyBudget": 150.00,
    "lifetimeBudget": null,
    "currency": "EUR",
    "bidStrategy": "LOWEST_COST_WITHOUT_CAP",
    "specialAdCategories": [],
    "lastSyncedAt": "2026-03-10T14:00:00Z",
    "createdAt": "2026-02-15T10:00:00Z",
    "updatedAt": "2026-03-10T14:00:00Z",
    "adSets": [
      {
        "id": "adset_xyz789",
        "metaAdSetId": "23851234567900",
        "name": "Broad Lookalike 1%",
        "status": "ACTIVE",
        "learningPhaseStatus": "EXITED",
        "dailyBudget": 60.00,
        "targeting": {
          "geoLocations": ["US", "CA"],
          "ageMin": 25,
          "ageMax": 54,
          "genders": ["all"]
        },
        "optimization": "CONVERSIONS",
        "adCount": 4
      },
      {
        "id": "adset_lmn456",
        "metaAdSetId": "23851234567901",
        "name": "Interest Stack - Fitness",
        "status": "ACTIVE",
        "learningPhaseStatus": "IN_LEARNING",
        "dailyBudget": 30.00,
        "targeting": {
          "geoLocations": ["US"],
          "ageMin": 18,
          "ageMax": 44,
          "genders": ["all"]
        },
        "optimization": "CONVERSIONS",
        "adCount": 3
      }
    ],
    "insights": {
      "spend": 5120.00,
      "impressions": 780000,
      "clicks": 15600,
      "conversions": 285,
      "cpa": 17.96,
      "roas": 2.4,
      "ctr": 2.0,
      "cpm": 6.56,
      "dateRange": "last_14d",
      "daily": [
        { "date": "2026-02-25", "spend": 148.50, "conversions": 22, "cpa": 6.75 },
        { "date": "2026-02-26", "spend": 151.20, "conversions": 24, "cpa": 6.30 }
      ]
    }
  }
}
```

***

## Error codes

| Status | Code                   | Description                                 |
| ------ | ---------------------- | ------------------------------------------- |
| `400`  | `invalid_request`      | Invalid query parameter format              |
| `401`  | `authentication_error` | Invalid or missing API key                  |
| `403`  | `plan_insufficient`    | API access requires the Agency plan         |
| `404`  | `not_found`            | Campaign not found or not in your workspace |
| `429`  | `rate_limit_error`     | Rate limit exceeded                         |
| `500`  | `api_error`            | Internal server error                       |