get_ad_performance
Aggregated metrics for a single ad over a date range. Use this for creative-fatigue analysis or sibling-ad comparisons within a campaign.
Parameters#
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
ad_account_id | string | yes | Ad account id | |
ad_id | string | yes | Platform ad id (from list_ads) | |
period_start | string | yes | YYYY-MM-DD, inclusive | |
period_end | string | yes | YYYY-MM-DD, inclusive; must be ≥ period_start | |
metrics | string[]? | no | [defaults] | Metric keys to sum. Defaults same as get_performance |
Returns#
json
{
"ad_account_id": "ad_acct_abc",
"ad_id": "987654",
"period_start": "2026-04-15",
"period_end": "2026-04-21",
"metrics": ["cost", "impressions", "clicks", "conversions", "conversion_value"],
"totals": {
"cost": 40.00,
"impressions": 300,
"clicks": 9,
"conversions": 1.5,
"conversion_value": 150.00
},
"row_count": 3,
"source": "adlyse.ads_ad_performance@v1"
}| Field | Description |
|---|---|
totals | Sum per metric across the window (always present; zeros when no data) |
row_count | Number of daily rows aggregated — use as a data-coverage sanity check |
Errors#
error_type | When |
|---|---|
auth_error | Missing / invalid API key |
not_found | Ad account doesn’t belong to your org |
validation_error | Bad date, unknown metric, period_end < period_start |
schema_error | Ad Metrics table is missing expected columns (shouldn’t happen in normal setups) |
Empty-rows semantics#
If the ad exists but has no rows in the window (for example, it was paused before the window started), the response returns row_count: 0 and all-zero totals. This is not an error — check row_count before interpreting zero metrics as a performance crisis.
Example#
Request:
json
{
"ad_account_id": "ad_acct_abc",
"ad_id": "987654",
"period_start": "2026-04-15",
"period_end": "2026-04-21",
"metrics": ["cost", "conversions", "ctr"]
}Response:
json
{
"ad_account_id": "ad_acct_abc",
"ad_id": "987654",
"period_start": "2026-04-15",
"period_end": "2026-04-21",
"metrics": ["cost", "conversions", "ctr"],
"totals": { "cost": 40.00, "conversions": 1.5, "ctr": 21.0 },
"row_count": 3,
"source": "adlyse.ads_ad_performance@v1"
}See also#
list_ads— discover ad idsget_performance— campaign-level or account-level aggregation