Accounts
The Accounts API provides access to the Meta ad accounts connected to your KlayrAI workspace.
List accounts
Retrieve all connected Meta ad accounts in your workspace.
Query parameters
| Parameter | Type | Required | Default | Description |
|---|
status | string | No | — | Filter by connection status: active, disconnected, token_expired |
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/accounts" \
-H "x-api-key: klyr_live_abc123def456ghi789" \
-H "klayrai-version: 2026-03-01"
Response
{
"data": [
{
"id": "act_001",
"metaAccountId": "act_123456789",
"name": "Acme Corp - Main",
"currency": "EUR",
"timezone": "Europe/Amsterdam",
"status": "active",
"connectionStatus": "active",
"businessName": "Acme Corporation",
"businessId": "1234567890",
"permissions": ["read_insights", "read_campaigns", "read_ads"],
"lastSyncedAt": "2026-03-10T14:00:00Z",
"campaignCount": 12,
"activeCampaignCount": 5,
"totalSpendLast30d": 14200.00,
"connectedAt": "2026-02-10T08:00:00Z",
"connectedBy": "user_abc123"
},
{
"id": "act_002",
"metaAccountId": "act_987654321",
"name": "Acme Corp - EU Market",
"currency": "EUR",
"timezone": "Europe/Berlin",
"status": "active",
"connectionStatus": "active",
"businessName": "Acme Corporation",
"businessId": "1234567890",
"permissions": ["read_insights", "read_campaigns", "read_ads"],
"lastSyncedAt": "2026-03-10T14:00:00Z",
"campaignCount": 8,
"activeCampaignCount": 3,
"totalSpendLast30d": 8750.00,
"connectedAt": "2026-02-15T09:30:00Z",
"connectedBy": "user_abc123"
}
],
"pagination": {
"total": 2,
"page": 1,
"page_size": 20,
"hasMore": false
}
}
Account object fields
| Field | Type | Description |
|---|
id | string | KlayrAI account ID |
metaAccountId | string | Meta ad account ID (format: act_XXXXXXXXX) |
name | string | Account name as set in Meta Business Manager |
currency | string | Account currency (ISO 4217) |
timezone | string | Account timezone (IANA format) |
status | string | Meta account status: active, disabled, closed |
connectionStatus | string | KlayrAI connection status: active, disconnected, token_expired |
businessName | string | Parent business name |
businessId | string | Meta Business Manager ID |
permissions | string[] | Granted permissions |
lastSyncedAt | string | ISO 8601 timestamp of last data sync |
campaignCount | integer | Total campaigns in the account |
activeCampaignCount | integer | Currently active campaigns |
totalSpendLast30d | number | Total spend in the last 30 days (in account currency) |
connectedAt | string | ISO 8601 timestamp when the account was connected |
connectedBy | string | User ID who connected the account |
Connection statuses
| Status | Description | Action required |
|---|
active | Account is connected and syncing normally | None |
disconnected | User manually disconnected the account | Reconnect via the dashboard |
token_expired | Meta access token has expired | Re-authenticate via the dashboard |
When a token expires, KlayrAI stops syncing data for that account. Diagnostics and reports will still be available for historical data, but new data will not be pulled until the account is re-authenticated.
Error codes
| Status | Code | Description |
|---|
400 | invalid_request | Invalid query parameters |
401 | authentication_error | Invalid or missing API key |
403 | plan_insufficient | API access requires the Agency plan |
429 | rate_limit_error | Rate limit exceeded |
500 | api_error | Internal server error |
