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"

const params = new URLSearchParams({
  status: "completed",
  page: "1",
  page_size: "10",
});

const response = await fetch(
  `https://api.klayrai.com/v1/reports?${params}`,
  {
    headers: {
      "x-api-key": "klyr_live_abc123def456ghi789",
      "klayrai-version": "2026-03-01",
    },
  }
);

const data = await response.json();

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"
  }'

const response = await fetch(
  "https://api.klayrai.com/v1/reports",
  {
    method: "POST",
    headers: {
      "x-api-key": "klyr_live_abc123def456ghi789",
      "klayrai-version": "2026-03-01",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      account_id: "act_123456789",
      title: "Weekly Performance Report - Summer Sale 2026",
      date_start: "2026-03-03",
      date_end: "2026-03-10",
    }),
  }
);

const data = await response.json();

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

​Reports

​List reports

​Query parameters

​Request

​Response

​Generate a report

​Request body

​Request

​Response

​Download a report

​Error codes

Reports

List reports

Query parameters

Request

Response

Generate a report

Request body

Request

Response

Download a report

Error codes