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
| Parameter | Type | Required | Default | Description |
|---|
campaignId | string | No | — | Filter by campaign ID |
accountId | string | No | — | Filter by ad account ID |
status | string | No | — | Filter by status: pending, generating, completed, failed |
format | string | No | — | Filter by format: json, pdf, markdown |
from | string | No | — | Start date for report creation (ISO 8601) |
to | string | No | — | End date for report creation (ISO 8601) |
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/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
| Parameter | Type | Required | Description |
|---|
account_id | string | Yes | The Meta ad account ID |
title | string | Yes | Report title |
date_start | string | Yes | Start date in YYYY-MM-DD format |
date_end | string | Yes | End 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
| Status | Code | Description |
|---|
400 | invalid_request | Missing or invalid parameters |
400 | too_many_campaigns | More than 20 campaign IDs provided |
401 | authentication_error | Invalid or missing API key |
403 | plan_insufficient | API access requires the Agency plan |
403 | white_label_not_available | White-label requires the Agency plan |
404 | not_found | One or more campaign IDs not found |
429 | rate_limit_error | Rate limit exceeded |
500 | api_error | Internal server error |
