Report ad cohorts

Payback by acquisition cohort: ROAS, revenue per payer or payers by day since acquisition, per weekly or monthly cohort and per surface, platform, campaign or ad group.

Money is in minor units of currency. Safe to repeat. Needs project:ads:read and project:analytics:read.

Guide: Ads reports

Errors

Status	`type`	`code`	When
400	`invalid_request`	`invalid_report`	For a range or time zone it cannot report on.
403	`permission_denied`	`permission_denied`	Without `project:analytics:read`.

It can also fail with the errors every operation shares, such as unauthenticated; see Errors.

More in Ads

Something wrong or missing on this page? Tell us by email or on Discord.

Path parameters

projectId*string

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.

from*string

The first day of the range, YYYY-MM-DD in timezone.

to*string

The last day of the range, inclusive, YYYY-MM-DD in timezone. A report spans at most 366 days.

currency?|

ISO 4217 code to report money in. Defaults to the project's reporting currency, else the connected accounts' when they share one, else USD.

timezone?|

IANA time zone the days are cut in, such as Europe/Prague. Defaults to the connected accounts' when they share one, else UTC.

environment?|

Environment measured purchases are read from: production, sandbox (store sandboxes such as TestFlight) or test (simulated purchases). Defaults to production.

groupBy*string

What each curve in groups is for: a surface (web, iOS, Android), an ad platform, a campaign or an ad_group.

Value in

"surface"
"platform"
"campaign"
"ad_group"

unit*string

Whether cohorts are of a week or a month of acquisition.

Value in

"week"
"month"

metric*string

roas: cumulative net revenue per the cohort's spend, a decimal. revenue_per_payer: cumulative net revenue per payer, in minor units. payers: cumulative payers.

Value in

"roas"
"revenue_per_payer"
"payers"

Examples

curl -X POST "https://api.voidhash.com/api/v1/projects/proj_tz4a98xxat96iws9zmbrgj3a/ads/reports/cohorts" \  -H "Authorization: Bearer vh_sk_..." \  -H "Content-Type: application/json" \  -d '{    "from": "2026-03-02",    "to": "2026-03-08",    "timezone": "Europe/Prague",    "groupBy": "platform",    "unit": "week",    "metric": "roas"  }'

{  "from": "2026-03-02",  "to": "2026-03-08",  "currency": "USD",  "timezone": "Europe/Prague",  "environment": "production",  "hasMeasuredAccess": true,  "warnings": [],  "provisionalFrom": null,  "groupBy": "platform",  "unit": "week",  "metric": "roas",  "cohorts": [    {      "start": "2026-03-02",      "spend": 108920,      "people": 241,      "values": [        {          "day": 0,          "value": 0.0412,          "projected": null,          "isMaturing": false        },        {          "day": 7,          "value": 0.1874,          "projected": null,          "isMaturing": false        },        {          "day": 30,          "value": 0.4483,          "projected": {            "value": 0.463,            "low": 0.441,            "high": 0.492,            "isPartial": false          },          "isMaturing": true        },        {          "day": 90,          "value": null,          "projected": {            "value": 0.912,            "low": 0.78,            "high": 1.06,            "isPartial": false          },          "isMaturing": true        }      ]    }  ],  "average": {    "spend": 108920,    "people": 241,    "values": [      {        "day": 0,        "value": 0.0412,        "projected": null      },      {        "day": 7,        "value": 0.1874,        "projected": null      },      {        "day": 30,        "value": 0.4483,        "projected": {          "value": 0.463,          "low": 0.441,          "high": 0.492,          "isPartial": false        }      },      {        "day": 90,        "value": null,        "projected": {          "value": 0.912,          "low": 0.78,          "high": 1.06,          "isPartial": false        }      }    ]  },  "groups": [    {      "key": "meta",      "name": null,      "surface": null,      "people": 241,      "values": [        {          "day": 0,          "value": 0.0412,          "projected": null        },        {          "day": 7,          "value": 0.1874,          "projected": null        },        {          "day": 30,          "value": 0.4483,          "projected": {            "value": 0.463,            "low": 0.441,            "high": 0.492,            "isPartial": false          }        },        {          "day": 90,          "value": null,          "projected": {            "value": 0.912,            "low": 0.78,            "high": 1.06,            "isPartial": false          }        }      ],      "paybackDay": null,      "paybackProbability": 0.42    }  ]}

{  "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."  }}

Report ad cohorts

Errors

More in Ads

Report ad cohorts

Errors

More in Ads

Authorization

Path parameters

Request body

Examples

Response body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Report ad cohorts

Report ad cohorts

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`