# Get reporting data GET https://services.leadconnectorhq.com/ad-publishing/facebook/reporting 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`. ## Authentication Send `Authorization: Bearer ` using: - **Sub-Account token: OAuth access token or Private Integration Token.** Scopes: `adPublishing.readonly` ## Parameters ### Header Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Version` | string | Yes | API Version | ### Query Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `locationId` | string | Yes | Location identifier | | `fields` | array | Yes | Reporting fields. Pass as comma-separated values on the wire (e.g. ?fields=impressions,clicks). | | `groupBy` | string | No | Time grouping interval | | `startDate` | string | Yes | Report start date (YYYY-MM-DD) | | `endDate` | string | Yes | Report end date (YYYY-MM-DD) | | `type` | string | Yes | Integration source type | ## OpenAPI Specification ```json { "openapi": "3.0.0", "info": { "title": "HighLevel API", "version": "2021-04-15" }, "servers": [ { "url": "https://services.leadconnectorhq.com" } ], "paths": { "/ad-publishing/facebook/reporting": { "get": { "summary": "Get reporting data", "operationId": "getReportingData", "description": "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`.", "parameters": [ { "name": "Version", "in": "header", "description": "API Version", "required": true, "schema": { "type": "string", "enum": [ "2021-04-15" ] } }, { "name": "locationId", "required": true, "in": "query", "description": "Location identifier", "schema": { "example": "fRMewNQIxSyZ5R4nQyit", "type": "string" } }, { "name": "fields", "required": true, "in": "query", "description": "Reporting fields. Pass as comma-separated values on the wire (e.g. ?fields=impressions,clicks).", "schema": { "example": [ "impressions", "clicks", "spend" ], "type": "array", "items": { "type": "string", "enum": [ "impressions", "clicks", "spend", "cpc", "cost_per_conversion", "conversions", "results", "cost_per_result", "cpm", "reach", "frequency", "ctr" ] } } }, { "name": "groupBy", "required": false, "in": "query", "description": "Time grouping interval", "schema": { "example": "month", "enum": [ "day", "week", "month" ], "type": "string" } }, { "name": "startDate", "required": true, "in": "query", "description": "Report start date (YYYY-MM-DD)", "schema": { "example": "2022-01-11", "type": "string" } }, { "name": "endDate", "required": true, "in": "query", "description": "Report end date (YYYY-MM-DD)", "schema": { "example": "2022-01-31", "type": "string" } }, { "name": "type", "required": true, "in": "query", "description": "Integration source type", "schema": { "example": "INTEGRATION", "enum": [ "AD_MANAGER", "INTEGRATION" ], "type": "string" } } ], "responses": { "200": { "description": "Per-period rows and their aggregate totals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookReportingResponseDTO" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestDTO" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedDTO" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableDTO" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorDTO" } } } } }, "security": [ { "bearer": [ "adPublishing.readonly" ] } ] } } }, "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.", "type": "http" }, "Location-Access": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.", "type": "http" }, "Location-Access-Only": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Sub-Account.", "type": "http" }, "Agency-Access": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Agency (OR) Private Integration Token of Agency.", "type": "http" }, "Agency-Access-Only": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Agency.", "type": "http" } }, "schemas": { "FacebookReportingResponseDTO": { "type": "object", "properties": { "grouped": { "description": "One row per period when `groupBy` is given, otherwise a single row covering the whole range.", "example": [ { "dateStart": "2026-03-01", "dateStop": "2026-03-31", "locationId": "fRMewNQIxSyZ5R4nQyit", "accountId": "act_357046700569338", "impressions": "99873", "clicks": "2304", "spend": "41.47", "cpc": "0.017999", "cpm": "0.415227", "ctr": "2.413273", "reach": "650", "frequency": "1.02", "conversions": 61, "results": { "lead": 61, "linkClick": 1940, "onsiteConversion.leadGrouped": 61 }, "costPerConversion": 0.679836, "costPerResultBreakdown": { "lead": 0.679836, "linkClick": 0.021376 } } ], "type": "array", "items": { "type": "object", "properties": { "dateStart": { "type": "string", "description": "First day of the period, inclusive", "example": "2026-03-01" }, "dateStop": { "type": "string", "description": "Last day of the period, inclusive. Clamped to the requested `endDate` on the final period.", "example": "2026-03-31" }, "locationId": { "type": "string", "description": "Location the report was run for", "example": "fRMewNQIxSyZ5R4nQyit" }, "accountId": { "type": "string", "description": "Ad account the insights came from", "example": "act_357046700569338" }, "impressions": { "type": "string", "description": "Impressions, as a string from Meta", "example": "99873" }, "clicks": { "type": "string", "description": "Clicks, as a string from Meta", "example": "2304" }, "spend": { "type": "string", "description": "Spend in account currency, as a string from Meta", "example": "41.47" }, "cpc": { "type": "string", "description": "Cost per click. Absent when the period had no clicks rather than reported as zero.", "example": "0.017999" }, "cpm": { "type": "string", "description": "Cost per thousand impressions", "example": "0.415227" }, "ctr": { "type": "string", "description": "Click-through rate as a percentage, not a fraction", "example": "2.413273" }, "reach": { "type": "string", "description": "Unique people reached", "example": "650" }, "frequency": { "type": "string", "description": "Average impressions per person reached", "example": "1.02" }, "conversions": { "type": "number", "description": "Lead actions only, summed. A number here, unlike the string metrics above.", "example": 61 }, "results": { "type": "object", "description": "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.", "additionalProperties": { "type": "number" }, "example": { "lead": 61, "linkClick": 1940, "onsiteConversion.leadGrouped": 61 } }, "costPerConversion": { "type": "number", "description": "Cost per lead action for the period", "example": 0.679836 }, "costPerResultBreakdown": { "type": "object", "description": "Cost per action, per action type, for the period", "additionalProperties": { "type": "number" }, "example": { "lead": 0.679836, "linkClick": 0.021376 } } }, "title": "FacebookReportingGroupedRowDTO" } }, "totals": { "description": "Aggregates across every row in `grouped`", "example": { "impressions": "298574.00", "clicks": "5150.00", "spend": "115.94", "cpc": "0.02", "cpm": "96.04", "ctr": "4.21", "reach": "650.00", "frequency": "1.02", "conversions": "255.00", "cost_per_conversion": 0, "costPerConversion": "0.45", "results": "34315.00", "resultsBreakdown": { "lead": "255", "linkClick": "4236" }, "cost_per_result": 0, "costPerResult": "0.00", "costPerResultBreakdown": { "lead": "0.4391", "linkClick": "0.0273" } }, "allOf": [ { "type": "object", "properties": { "impressions": { "type": "string", "description": "Summed impressions", "example": "298574.00" }, "clicks": { "type": "string", "description": "Summed clicks", "example": "5150.00" }, "spend": { "type": "string", "description": "Summed spend", "example": "115.94" }, "cpc": { "type": "string", "description": "Recomputed correctly as total spend divided by total clicks", "example": "0.02" }, "cpm": { "type": "string", "description": "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" }, "ctr": { "type": "string", "description": "Sum of the per-period CTR percentages, not a weighted average. Same caveat as `cpm`.", "example": "4.21" }, "reach": { "type": "string", "description": "Summed reach. Counts a person once per period, so repeats across periods.", "example": "650.00" }, "frequency": { "type": "string", "description": "Sum of the per-period frequency values, not a weighted average.", "example": "1.02" }, "conversions": { "description": "Summed lead actions", "oneOf": [ { "type": "number" }, { "type": "string" } ], "example": "255.00" }, "cost_per_conversion": { "type": "number", "description": "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 }, "costPerConversion": { "type": "string", "description": "The real cost per lead: total spend divided by total lead actions.", "example": "0.45" }, "results": { "type": "string", "description": "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" }, "resultsBreakdown": { "type": "object", "description": "Counts per action type summed across periods. String values here, unlike the numbers in `grouped`.", "additionalProperties": { "type": "string" }, "example": { "lead": "255", "linkClick": "4236" } }, "cost_per_result": { "type": "number", "description": "Always the number `0`, never the real value. Read `costPerResult` instead — same placeholder behaviour as `cost_per_conversion`.", "example": 0 }, "costPerResult": { "type": "string", "description": "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" }, "costPerResultBreakdown": { "type": "object", "description": "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.", "additionalProperties": { "type": "string" }, "example": { "lead": "0.4391", "linkClick": "0.0273" } } }, "title": "FacebookReportingTotalsDTO" } ] } }, "required": [ "grouped", "totals" ], "title": "FacebookReportingResponseDTO" }, "BadRequestDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 400 }, "message": { "type": "string", "example": "Bad Request" } }, "title": "BadRequestDTO" }, "UnauthorizedDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 401 }, "message": { "type": "string", "example": "Invalid token: access token is invalid" }, "error": { "type": "string", "example": "Unauthorized" } }, "title": "UnauthorizedDTO" }, "UnprocessableDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 422 }, "message": { "example": [ "Unprocessable Entity" ], "type": "array", "items": { "type": "string" } }, "error": { "type": "string", "example": "Unprocessable Entity" } }, "title": "UnprocessableDTO" }, "InternalServerErrorDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "HTTP status code for an unexpected server error", "example": 500 }, "message": { "type": "string", "description": "Error message describing the server failure", "example": "Internal Server Error" } }, "title": "InternalServerErrorDTO" } } } } ``` ## Code Examples **cURL** ```bash curl -L -X GET 'https://services.leadconnectorhq.com/ad-publishing/facebook/reporting?locationId=&fields=&startDate=&endDate=&type=' \ -H 'Authorization: Bearer ' \ -H 'Version: 2021-04-15' ``` **Node.js** ```javascript const options = { method: 'GET', headers: { Authorization: 'Bearer ', Version: '2021-04-15' } }; try { const response = await fetch('https://services.leadconnectorhq.com/ad-publishing/facebook/reporting?locationId=&fields=&startDate=&endDate=&type=', options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` **Python** ```python import requests url = "https://services.leadconnectorhq.com/ad-publishing/facebook/reporting" headers = { "Authorization": "Bearer ", "Version": "2021-04-15" } params = { "locationId": "", "fields": "", "startDate": "", "endDate": "", "type": "" } response = requests.get(url, params=params, headers=headers) print(response.json()) ``` **PHP** ```php 'https://services.leadconnectorhq.com/ad-publishing/facebook/reporting?locationId=&fields=&startDate=&endDate=&type=', CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'GET', CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ', 'Version: 2021-04-15', ], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ``` **Java** ```java HttpResponse response = Unirest .get("https://services.leadconnectorhq.com/ad-publishing/facebook/reporting?locationId=&fields=&startDate=&endDate=&type=") .header("Authorization", "Bearer ") .header("Version", "2021-04-15") .asString(); ``` **Go** ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://services.leadconnectorhq.com/ad-publishing/facebook/reporting?locationId=&fields=&startDate=&endDate=&type=" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Version", "2021-04-15") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(string(body)) } ``` **Ruby** ```ruby require 'uri' require 'net/http' url = URI("https://services.leadconnectorhq.com/ad-publishing/facebook/reporting?locationId=&fields=&startDate=&endDate=&type=") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = "Bearer " request["Version"] = "2021-04-15" response = http.request(request) puts response.read_body ``` **PowerShell** ```powershell $headers = @{ "Authorization" = "Bearer " "Version" = "2021-04-15" } $response = Invoke-RestMethod -Uri 'https://services.leadconnectorhq.com/ad-publishing/facebook/reporting?locationId=&fields=&startDate=&endDate=&type=' -Method 'GET' -Headers $headers $response | ConvertTo-Json ```