Retrieve aggregated Facebook ad reporting metrics for a location. grouped holds one row per groupBy period, or a single row covering the whole range when groupBy is omitted, and totals aggregates across them. Both objects only carry the metrics named in fields. Be aware that ratio metrics (cpm, ctr, frequency) are summed rather than weighted in totals, and that cost_per_conversion and cost_per_result are placeholders that always read 0 — their real values live under costPerConversion and costPerResult.
Authorizations
Authorizationstringheaderrequired
Bearer authentication header of the form Bearer <token>, where <token> is your access token.
Reporting fields. Pass as comma-separated values on the wire (e.g. ?fields=impressions,clicks).
Available optionsimpressionsclicksspendcpccost_per_conversionconversionsresultscost_per_resultcpmreachfrequencyctr
Example:["impressions","clicks","spend"]
groupBystring
Time grouping interval
Available optionsdayweekmonth
Example:month
startDatestringrequired
Report start date (YYYY-MM-DD)
Example:2022-01-11
endDatestringrequired
Report end date (YYYY-MM-DD)
Example:2022-01-31
typestringrequired
Integration source type
Available optionsAD_MANAGERINTEGRATION
Example:INTEGRATION
Response
application/json
Per-period rows and their aggregate totals
groupedobject[]required
One row per period when groupBy is given, otherwise a single row covering the whole range.
grouped[].dateStartstring
First day of the period, inclusive
Example:2026-03-01
grouped[].dateStopstring
Last day of the period, inclusive. Clamped to the requested endDate on the final period.
Example:2026-03-31
grouped[].locationIdstring
Location the report was run for
Example:fRMewNQIxSyZ5R4nQyit
grouped[].accountIdstring
Ad account the insights came from
Example:act_357046700569338
grouped[].impressionsstring
Impressions, as a string from Meta
Example:99873
grouped[].clicksstring
Clicks, as a string from Meta
Example:2304
grouped[].spendstring
Spend in account currency, as a string from Meta
Example:41.47
grouped[].cpcstring
Cost per click. Absent when the period had no clicks rather than reported as zero.
Example:0.017999
grouped[].cpmstring
Cost per thousand impressions
Example:0.415227
grouped[].ctrstring
Click-through rate as a percentage, not a fraction
Example:2.413273
grouped[].reachstring
Unique people reached
Example:650
grouped[].frequencystring
Average impressions per person reached
Example:1.02
grouped[].conversionsnumber
Lead actions only, summed. A number here, unlike the string metrics above.
Example:61
grouped[].resultsobject
Counts per Meta action type, keys camelCased from Meta except where the type itself contains a dot (onsiteConversion.leadGrouped). These action types overlap by design — pageEngagement already contains postEngagement, which contains linkClick — so summing the values double-counts.
Recomputed correctly as total spend divided by total clicks
Example:0.02
totals.cpmstring
Sum of the per-period CPM values, NOT a spend-weighted average. A period with a single impression contributes its whole inflated CPM, so this total can exceed every individual period. Compute spend / impressions * 1000 yourself if you need the real figure.
Example:96.04
totals.ctrstring
Sum of the per-period CTR percentages, not a weighted average. Same caveat as cpm.
Example:4.21
totals.reachstring
Summed reach. Counts a person once per period, so repeats across periods.
Example:650.00
totals.frequencystring
Sum of the per-period frequency values, not a weighted average.
Example:1.02
totals.conversionsobject
Summed lead actions
oneOf
number
string
number
totals.cost_per_conversionnumber
Always the number 0, never the real value. The field is seeded to zero and the computed figure is written to costPerConversion instead, so this key is a placeholder — read costPerConversion.
Example:0
totals.costPerConversionstring
The real cost per lead: total spend divided by total lead actions.
Example:0.45
totals.resultsstring
Sum of every value in resultsBreakdown. Because Meta action types nest inside one another this double-counts heavily and is not a meaningful count of anything.
Example:34315.00
totals.resultsBreakdownobject
Counts per action type summed across periods. String values here, unlike the numbers in grouped.
totals.resultsBreakdown.property name*string
totals.cost_per_resultnumber
Always the number 0, never the real value. Read costPerResult instead — same placeholder behaviour as cost_per_conversion.
Example:0
totals.costPerResultstring
Total spend divided by the double-counted results total, rounded to two decimals. Because the denominator is inflated this is usually a very small number that rounds to "0.00" — the per-action figures in costPerResultBreakdown are the usable ones.
Example:0.00
totals.costPerResultBreakdownobject
Cost per action, per action type, aggregated as total spend over total count rather than by averaging the per-period ratios. Carries four decimals where the scalar totals carry two.