Returning visitors by cohort, across projects
Each project's visitors counted separately.
An API token from POST /v2/tokens (at_live_...), or a project's secret key (sk_...) for server-side ingest.
In: header
Query Parameters
Start of the range; send with to.
date-timeEnd of the range, exclusive.
date-timeA range ending at the start of today in UTC (24h ends at the start of this hour). Ignored when from and to are sent; 30d by default.
Value in
- "24h"
- "7d"
- "30d"
- "90d"
- "12mo"
- "all"
Which traffic is counted. human (the default) leaves out bot scores of 50 and up, your own visits and localhost; bots keeps only scores of 50 and up; internal keeps only your own visits; all keeps everything.
Value in
- "human"
- "bots"
- "internal"
- "all"
production (the default) leaves preview deployments out, preview keeps only them, all keeps both.
Value in
- "production"
- "preview"
- "all"
Sent as filter[<dimension>]=value, or !value to exclude; repeatable across dimensions.
Cohort size: week (the default, starting Monday) or month, in UTC.
Value in
- "week"
- "month"
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v2/retention"{ "data": [ { "cohort": "2026-09-07T00:00:00.000Z", "visitors": 120, "periods": [ { "offset": 0, "visitors": 120, "share": 1 }, { "offset": 1, "visitors": 22, "share": 0.183 }, { "offset": 2, "visitors": 14, "share": 0.117 }, { "offset": 3, "visitors": 9, "share": 0.075 } ] }, { "cohort": "2026-09-14T00:00:00.000Z", "visitors": 96, "periods": [ { "offset": 0, "visitors": 96, "share": 1 }, { "offset": 1, "visitors": 17, "share": 0.177 }, { "offset": 2, "visitors": 10, "share": 0.104 } ] } ], "interval": "week", "range": { "from": "2026-08-31T00:00:00.000Z", "to": "2026-09-28T00:00:00.000Z" }, "traffic": "human", "environment": "production", "filters": {}}