Report acquisition cohorts
Weekly cohorts of the people a touch acquired, by acquisition date (the day of the touch credited with each signup, within the attribution window), grouped by surface, network, campaign or ad set: cumulative signups, payers and revenue by day 0, 1, 3, 7, 14, 30, 60, 90, 180, 365 and 730 after each person's touch, each complete or still maturing, with projections of the net revenue still to come.
Money is in integer minor units of currency.
Guide: Analytics overview
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.
Only people whose credited touch carried this ad set id.
How many days, 1 to 90, before a signup a touch can be credited with it. Defaults to the project's attribution window.
Only people whose credited touch carried this campaign id.
The ISO 4217 code money is reported in. Amounts in another currency are converted at each day's exchange rate. Defaults to USD.
The environment whose revenue counts: production (the default), sandbox or test. Visits come from production keys, or from test keys for test; signups count in every environment.
The first acquisition day, YYYY-MM-DD, in the report time zone.
What cohorts group by: the surface people signed up on (surface), or the credited touch's network, campaign or adset.
Value in
- "surface"
- "network"
- "campaign"
- "adset"
Only people whose credited touch came from this ad network, such as meta. Compared in lowercase.
The IANA time zone that sets day boundaries, such as the ad account's. Offsets such as +01:00 are rejected. Defaults to UTC.
The last acquisition day, inclusive, YYYY-MM-DD.
Examples
curl -X POST "https://api.voidhash.com/api/v1/projects/proj_tz4a98xxat96iws9zmbrgj3a/analytics/reports/acquisition-cohorts" \ -H "Authorization: Bearer vh_sk_..." \ -H "Content-Type: application/json" \ -d '{ "from": "2026-03-02", "to": "2026-03-08", "groupBy": "network", "network": "meta" }'{ "projectId": "proj_tz4a98xxat96iws9zmbrgj3a", "groupBy": "network", "currency": "USD", "timezone": "UTC", "environment": "production", "attributionWindowDays": 7, "from": "2026-03-02", "to": "2026-03-08", "start": "2026-03-02T00:00:00.000Z", "end": "2026-03-09T00:00:00.000Z", "asOf": "2026-04-02T08:00:00.000Z", "days": [ 0, 1, 3, 7, 14, 30, 60, 90, 180, 365, 730 ], "groups": [ { "network": "meta", "campaignId": null, "campaignName": null, "adsetId": null, "adsetName": null, "adId": null, "adName": null, "surface": null, "cohorts": [ { "week": "2026-03-02", "from": "2026-03-02", "to": "2026-03-08", "people": 241, "cells": [ { "day": 0, "people": 241, "payingPeople": 4, "grossRevenue": 3996, "refunds": 0, "netRevenue": 3996, "maturity": "complete" }, { "day": 1, "people": 241, "payingPeople": 6, "grossRevenue": 5994, "refunds": 0, "netRevenue": 5994, "maturity": "complete" }, { "day": 3, "people": 241, "payingPeople": 9, "grossRevenue": 10992, "refunds": 0, "netRevenue": 10992, "maturity": "complete" }, { "day": 7, "people": 241, "payingPeople": 19, "grossRevenue": 21381, "refunds": 0, "netRevenue": 21381, "maturity": "complete" }, { "day": 14, "people": 241, "payingPeople": 31, "grossRevenue": 34869, "refunds": 999, "netRevenue": 33870, "maturity": "complete" }, { "day": 30, "people": 241, "payingPeople": 42, "grossRevenue": 49812, "refunds": 999, "netRevenue": 48813, "maturity": "maturing" } ], "projections": [ { "day": 30, "netRevenue": 50430, "low": 48990, "high": 52110, "isPartial": false }, { "day": 60, "netRevenue": 71240, "low": 64800, "high": 78300, "isPartial": false }, { "day": 90, "netRevenue": 89960, "low": 79100, "high": 101400, "isPartial": false }, { "day": 180, "netRevenue": 131800, "low": 109200, "high": 156900, "isPartial": false }, { "day": 365, "netRevenue": 198300, "low": 152600, "high": 251700, "isPartial": true }, { "day": 730, "netRevenue": 286500, "low": 201400, "high": 389200, "isPartial": true } ] } ] } ], "total": [ { "week": "2026-03-02", "from": "2026-03-02", "to": "2026-03-08", "people": 241, "cells": [ { "day": 0, "people": 241, "payingPeople": 4, "grossRevenue": 3996, "refunds": 0, "netRevenue": 3996, "maturity": "complete" }, { "day": 1, "people": 241, "payingPeople": 6, "grossRevenue": 5994, "refunds": 0, "netRevenue": 5994, "maturity": "complete" }, { "day": 3, "people": 241, "payingPeople": 9, "grossRevenue": 10992, "refunds": 0, "netRevenue": 10992, "maturity": "complete" }, { "day": 7, "people": 241, "payingPeople": 19, "grossRevenue": 21381, "refunds": 0, "netRevenue": 21381, "maturity": "complete" }, { "day": 14, "people": 241, "payingPeople": 31, "grossRevenue": 34869, "refunds": 999, "netRevenue": 33870, "maturity": "complete" }, { "day": 30, "people": 241, "payingPeople": 42, "grossRevenue": 49812, "refunds": 999, "netRevenue": 48813, "maturity": "maturing" } ], "projections": [ { "day": 30, "netRevenue": 50430, "low": 48990, "high": 52110, "isPartial": false }, { "day": 60, "netRevenue": 71240, "low": 64800, "high": 78300, "isPartial": false }, { "day": 90, "netRevenue": 89960, "low": 79100, "high": 101400, "isPartial": false }, { "day": 180, "netRevenue": 131800, "low": 109200, "high": 156900, "isPartial": false }, { "day": 365, "netRevenue": 198300, "low": 152600, "high": 251700, "isPartial": true }, { "day": 730, "netRevenue": 286500, "low": 201400, "high": 389200, "isPartial": true } ] } ], "projection": { "plans": [ { "billingPeriod": "monthly", "store": "apple-app-store", "subscriptions": 2140, "basis": "plan" }, { "billingPeriod": "annual", "store": "apple-app-store", "subscriptions": 380, "basis": "plan" } ] }}{ "error": { "type": "invalid_request", "code": "invalid_report_request", "message": "At most 20 insight queries are allowed per batch" }}{ "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_request | And a message saying what to change. |
| 400 | invalid_request | invalid_time_range | And a message saying what to change. |
It can also fail with the errors every operation shares, such as unauthenticated; see Errors.
More in Analytics
- Compute insights
POST - Compute charts
POST - Report acquisition
POST - Report tracking health
POST - List live users
POST
Something wrong or missing on this page? Tell us by email or on Discord.