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 -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"
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();
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 -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"
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();
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 |