get_performance
Aggregated, cross-platform performance for an ad account over a date range. Optionally grouped by date, campaign, platform, or campaign status.
Parameters#
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
ad_account_id | string | yes | Ad account id | |
period_start | string | yes | YYYY-MM-DD, inclusive | |
period_end | string | yes | YYYY-MM-DD, inclusive; must be ≥ period_start | |
group_by | string? | no | null | One of "date", "campaign", "platform", "campaign_status", or null |
metrics | string[]? | no | [cost, impressions, clicks, conversions, conversion_value] | Metric column keys to sum. See valid metrics. |
Valid metric keys#
Any numeric column on the Ad Campaign Metrics table:
cost,impressions,clicks,conversions,conversion_value(defaults)ctr,cpc,cpa,roasdaily_budget
Ratio metrics like ctr/cpc/cpa/roas are summed by this tool — treat them as totals to be divided yourself if you need ratios in the rolled-up view. For per-row ratios, request group_by="campaign" / "date" and compute ratios from the per-group totals.
Returns#
json
{
"ad_account_id": "ad_acct_abc",
"period_start": "2026-04-15",
"period_end": "2026-04-21",
"group_by": "date",
"metrics": ["cost", "impressions", "clicks", "conversions", "conversion_value"],
"totals": {
"cost": 2040.87,
"impressions": 73500,
"clicks": 3570,
"conversions": 196,
"conversion_value": 19600
},
"rows": [
{ "group": "2026-04-15", "metrics": { "cost": 291.55, "impressions": 10500, "clicks": 510, "conversions": 28, "conversion_value": 2800 } },
{ "group": "2026-04-16", "metrics": { "cost": 297.32, "impressions": 10710, "clicks": 521, "conversions": 30, "conversion_value": 3000 } }
],
"row_count": 28,
"source": "adlyse.ads_performance@v1"
}| Field | Description |
|---|---|
totals | Sum of each metric across every matching row, always present |
rows | Per-group results when group_by is set; empty array when group_by=null |
row_count | Number of underlying source rows aggregated |
rows[].group | Value of the grouping key; for group_by="campaign", also includes campaign_name |
Errors#
error_type | When |
|---|---|
auth_error | Missing / invalid API key |
not_found | Ad account doesn’t belong to your org |
validation_error | Bad group_by, unknown/non-numeric metric, bad date, period_end < period_start |
Example#
Request:
json
{
"ad_account_id": "ad_acct_abc",
"period_start": "2026-04-15",
"period_end": "2026-04-21",
"group_by": "campaign",
"metrics": ["cost", "conversions"]
}Response (excerpt):
json
{
"totals": { "cost": 2040.87, "conversions": 196 },
"rows": [
{ "group": "c1", "campaign_name": "Brand Search - US", "metrics": { "cost": 1205.50, "conversions": 112 } },
{ "group": "c2", "campaign_name": "Retargeting - Core", "metrics": { "cost": 835.37, "conversions": 84 } }
],
"row_count": 28,
"source": "adlyse.ads_performance@v1"
}See also#
list_campaigns— discover campaign ids forgroup_by="campaign"get_ad_performance— per-ad aggregation