Report ad performance
Delivery and outcomes per campaign, ad group or ad over a range: what the platform reports (spend, impressions, clicks, results) next to the people, payers and revenue Voidhash measured from the signups credited to them.
Filtered, sorted and paged, with totals over every matching row, account spend no ad accounts for, and an optional breakdown of each row by placement, country, age, gender, device or surface. Ended and removed objects appear only when they delivered in the range. Platform-reported and Voidhash-measured numbers stay in separate objects; measured numbers need project:analytics:read and are null without it. Money is in minor units of currency, rates are decimals. Safe to repeat. Needs project:ads:read.
Guide: Ads reports
A project secret key: vh_sk_... for production, vh_sk_test_... for test. Keep it on your servers.
In: header
Path parameters
The project's id, proj_.... A secret key works only in the project it belongs to.
Request body
application/json
TypeScript definitions
Use the request body type in TypeScript.
The first day of the range, YYYY-MM-DD in timezone.
The last day of the range, inclusive, YYYY-MM-DD in timezone. A report spans at most 366 days.
ISO 4217 code to report money in. Defaults to the project's reporting currency, else the connected accounts' when they share one, else USD.
IANA time zone the days are cut in, such as Europe/Prague. Defaults to the connected accounts' when they share one, else UTC.
Environment measured purchases are read from: production, sandbox (store sandboxes such as TestFlight) or test (simulated purchases). Defaults to production.
The level of the ad hierarchy: campaign, ad_group (Meta: ad set) or ad.
Value in
- "campaign"
- "ad_group"
- "ad"
A dimension to slice each row by: surface slices measured numbers; placement, country, age, gender and device slice the platform's. Left out, rows are not sliced.
Only these campaigns, or the ad groups and ads under them, by the platform's ids. At most 100.
Only these ad groups, or the ads under them, by the platform's ids. At most 100.
Only objects that are active (delivering or learning) or that needs_attention (learning limited, not delivering, rejected, or held by an account issue).
Only objects whose ads send people to this destination.
Only those whose name contains this text, ignoring case, or whose id is exactly it. At most 200 characters.
Extra numbers to read. reach reads reach and frequency from the platform for the page's rows, which makes the report slower.
How rows are ordered. Defaults to spend, highest first. Rates sort with null last.
Rows per page, from 1 to 200; defaults to 50.
Where to resume: the pageInfo.endCursor of the previous page.
Examples
curl -X POST "https://api.voidhash.com/api/v1/projects/proj_tz4a98xxat96iws9zmbrgj3a/ads/reports/performance" \ -H "Authorization: Bearer vh_sk_..." \ -H "Content-Type: application/json" \ -d '{ "from": "2026-03-01", "to": "2026-03-31", "timezone": "Europe/Prague", "level": "campaign", "sort": { "field": "spend", "direction": "desc" } }'{ "data": [ { "id": "120210000000000001", "name": "Spring trial", "campaignId": "120210000000000001", "adGroupId": null, "deliveryStatus": "delivering", "destination": "web_to_app", "platformUrl": "https://adsmanager.facebook.com/adsmanager/manage/campaigns?act=1234567890&selected_campaign_ids=120210000000000001", "reported": { "spend": 482350, "impressions": 612400, "reach": null, "frequency": null, "linkClicks": 9186, "ctr": 0.015, "purchaseValue": 301200, "platformRoas": 0.6244, "results": [ { "type": "landing_page_view", "label": null, "count": 7412 }, { "type": "other", "label": "Trials started", "count": 296 } ] }, "measured": { "visits": 7020, "installs": 1204, "signups": 1046, "trials": 412, "payers": 168, "keyConversions": 168, "grossRevenue": 268430, "refunds": 4995, "netRevenue": 263435, "roas": 0.5461, "costPerSignup": 461, "costPerPayer": 2871, "costPerKeyConversion": 2871, "returningPayers": 7, "returningRevenue": 6993 }, "modeled": { "netRevenueHigh": 344717, "roasHigh": 0.7147, "visitCoverage": 0.7642 }, "breakdown": null } ], "pageInfo": { "endCursor": null, "hasNextPage": false }, "from": "2026-03-01", "to": "2026-03-31", "currency": "USD", "timezone": "Europe/Prague", "environment": "production", "hasMeasuredAccess": true, "warnings": [], "provisionalFrom": "2026-03-25", "level": "campaign", "breakdown": null, "keyConversion": "payer", "totals": { "reported": { "spend": 482350, "impressions": 612400, "reach": null, "frequency": null, "linkClicks": 9186, "ctr": 0.015, "purchaseValue": 301200, "platformRoas": 0.6244, "results": [ { "type": "landing_page_view", "label": null, "count": 7412 }, { "type": "other", "label": "Trials started", "count": 296 } ] }, "measured": { "visits": 7020, "installs": 1204, "signups": 1046, "trials": 412, "payers": 168, "keyConversions": 168, "grossRevenue": 268430, "refunds": 4995, "netRevenue": 263435, "roas": 0.5461, "costPerSignup": 461, "costPerPayer": 2871, "costPerKeyConversion": 2871, "returningPayers": 7, "returningRevenue": 6993 }, "modeled": { "netRevenueHigh": 344717, "roasHigh": 0.7147, "visitCoverage": 0.7642 } }, "unallocated": { "spend": 1250, "impressions": 830, "clicks": 21, "linkClicks": 9 }}{ "error": { "type": "invalid_request", "code": "invalid_report", "message": "Europe/Prag is not an IANA time zone." }}{ "error": { "type": "unauthenticated", "code": "invalid_api_key", "message": "This secret key is not valid." }}{ "error": { "type": "permission_denied", "code": "permission_denied", "message": "Insufficient permissions." }}{ "error": { "type": "not_found", "code": "project_not_found", "message": "There is no project proj_tz4a98xxat96iws9zmbrgj3a, or this credential cannot use it.", "param": "projectId" }}{ "error": { "type": "internal", "code": "internal_error", "message": "Something went wrong on our side. Try again, and contact support with the Request-Id header if it keeps failing." }}Response body
application/json
application/json
application/json
application/json
application/json
application/json
Errors
| Status | type | code | When |
|---|---|---|---|
| 400 | invalid_request | invalid_report | For a range or time zone it cannot report on. |
It can also fail with the errors every operation shares, such as unauthenticated; see Errors.
More in Ads
- List campaigns
GET - Retrieve a campaign
GET - List ad groups
GET - Retrieve an ad group
GET - List ads
GET - Retrieve an ad
GET - Preview a creative
GET - Retrieve ads settings
GET - Update ads settings
PATCH - Report creatives
POST - Report ad cohorts
POST - Report ad changes
POST
Something wrong or missing on this page? Tell us by email or on Discord.