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.

​
Reports

The Reports API lets you generate structured performance reports and retrieve them in JSON, PDF, or Markdown format. Reports combine campaign metrics with AI-generated analysis and recommendations.

​
List reports

Retrieve a paginated list of generated reports.

​
Query parameters

ParameterTypeRequiredDefaultDescription
campaignIdstringNo—Filter by campaign ID
accountIdstringNo—Filter by ad account ID
statusstringNo—Filter by status: pending, generating, completed, failed
formatstringNo—Filter by format: json, pdf, markdown
fromstringNo—Start date for report creation (ISO 8601)
tostringNo—End date for report creation (ISO 8601)
pageintegerNo1Page number
page_sizeintegerNo20Results per page (max 100)

​
Request

curl -X GET "https://api.klayrai.com/v1/reports?status=completed&page=1&page_size=10" \
  -H "x-api-key: klyr_live_abc123def456ghi789" \
  -H "klayrai-version: 2026-03-01"

​
Response

{
  "data": [
    {
      "id": "rpt_4m8n2k6p",
      "title": "Weekly Performance Report - Summer Sale 2026",
      "campaignIds": ["camp_abc123", "camp_def456"],
      "accountId": "act_001",
      "status": "completed",
      "format": "pdf",
      "dateRange": {
        "from": "2026-03-03",
        "to": "2026-03-10"
      },
      "summary": {
        "totalSpend": 3400.50,
        "totalConversions": 231,
        "avgCpa": 14.72,
        "avgRoas": 3.2,
        "overallRiskLevel": "MEDIUM"
      },
      "downloadUrl": "https://api.klayrai.com/v1/reports/rpt_4m8n2k6p/download",
      "expiresAt": "2026-03-17T14:00:00Z",
      "createdAt": "2026-03-10T14:00:00Z",
      "completedAt": "2026-03-10T14:00:12Z"
    }
  ],
  "pagination": {
    "total": 8,
    "page": 1,
    "page_size": 10,
    "hasMore": false
  }
}

​
Generate a report

Trigger the generation of a new performance report. Reports are generated asynchronously and typically take 10-20 seconds.

​
Request body

ParameterTypeRequiredDescription
account_idstringYesThe Meta ad account ID
titlestringYesReport title
date_startstringYesStart date in YYYY-MM-DD format
date_endstringYesEnd date in YYYY-MM-DD format

​
Request

curl -X POST "https://api.klayrai.com/v1/reports" \
  -H "x-api-key: klyr_live_abc123def456ghi789" \
  -H "klayrai-version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "act_123456789",
    "title": "Weekly Performance Report - Summer Sale 2026",
    "date_start": "2026-03-03",
    "date_end": "2026-03-10"
  }'

​
Response

{
  "data": {
    "id": "rpt_7j3k9m1n",
    "title": "Weekly Performance Report - Summer Sale 2026",
    "accountId": "act_123456789",
    "status": "generating",
    "dateRange": {
      "from": "2026-03-03",
      "to": "2026-03-10"
    },
    "createdAt": "2026-03-10T15:00:00Z",
    "estimatedCompletionSeconds": 15
  }
}
Poll GET /v1/reports to check for completion. The downloadUrl field will be populated once the report status is completed.

​
Download a report

The downloadUrl returned on completed reports is a signed URL valid for 7 days. Send a GET request to download the file directly: 
curl -o report.pdf "https://api.klayrai.com/v1/reports/rpt_4m8n2k6p/download" \
  -H "x-api-key: klyr_live_abc123def456ghi789"

​
Error codes

StatusCodeDescription
400invalid_requestMissing or invalid parameters
400too_many_campaignsMore than 20 campaign IDs provided
401authentication_errorInvalid or missing API key
403plan_insufficientAPI access requires the Agency plan
403white_label_not_availableWhite-label requires the Agency plan
404not_foundOne or more campaign IDs not found
429rate_limit_errorRate limit exceeded
500api_errorInternal server error