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

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

cURL

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"

Response

{
  "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

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

cURL

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"

Response

{
  "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