Skip to main content

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

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

ParameterTypeRequiredDefaultDescription
account_idstringNoFilter by connected ad account ID
pageintegerNo1Page number
page_sizeintegerNo20Results 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"

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

ParameterTypeRequiredDescription
idstringYesThe KlayrAI campaign ID (e.g., camp_abc123)

Query parameters

ParameterTypeRequiredDefaultDescription
includestringNoComma-separated list of related resources to include: adSets, ads, diagnostics, insights
insightsDateRangestringNolast_7dDate 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"

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

StatusCodeDescription
400invalid_requestInvalid query parameter format
401authentication_errorInvalid or missing API key
403plan_insufficientAPI access requires the Agency plan
404not_foundCampaign not found or not in your workspace
429rate_limit_errorRate limit exceeded
500api_errorInternal server error