VoidhashDocs
DevelopersHelp centerGuidesAPI reference
Dashboard
Essentials
API overview
Authentication
Event capture
Push device API
Webhooks
Webhook delivery
Webhook events
Projects & keys
Projects
API keys
Audit log
Customers & access
Persons
Products
Perks
Sandbox
Paywalls
Paywalls
Paywall locations
Components
Component registry
Assets
Experiments & flags
Experiments
Feature flags
Analytics & events
Analytics
Analytics alerts
Cohorts
Group types
Groups
Events
Ingest policy
VoidQL
Tracking domains
Ads
Ads
Ad accounts
Meta measurement
Payments & stores
Payment providers
Payment provider products
Purchase history imports
Payment sources
Webhooks & notifications
Webhooks
Push notifications
Push configurations
Automations
Organization & team
Organizations
Members
Invitations
Billing
Your account
Profile
Session
Notices
Connected apps
Terms of Service
Developer tools
Schema
SDK
Compute insights
Compute charts
Measure metrics
List the people behind a metric
Report acquisition
Report acquisition cohorts
Report tracking health
List live users

List the people behind a metric

Lists who is behind one point of a metric query's result: the people (or, for unique_groups, the groups) whose rows made that bucket's value, of the total or of one group of the split, read by the same query, filters and split as the point.

People are listed with the events they sent in the bucket (unique_sessions: their sessions; property: the statistic of their numbers; active people: their events in the window), revenue with what each paid net of refunds, and MRR with each person's MRR at the bucket's end, money in integer minor units of currency. A count of people or groups has as many actors as its value, and what adds up sums to it. A cumulative query's point reads from the range's start. Pages run by value, most first, then by key; total counts the point's actors. People need the project:persons:read permission as well as project:analytics:read; groups need analytics read alone.

Guide: Analytics overview

Errors

StatustypecodeWhen
400invalid_requestinvalid_report_requestWith a message saying what to change, such as a bucketStart that is not one of the result's buckets.
400invalid_requestinvalid_time_rangeWith a message saying what to change, such as a bucketStart that is not one of the result's buckets.

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

More in Analytics

  • Compute insights POST
  • Compute charts POST
  • Measure metrics POST
  • Report acquisition POST
  • Report acquisition cohorts POST
  • Report tracking health POST
  • List live users POST

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

PreviousMeasure metricsNextReport acquisition

On this page

AuthorizationPath parametersRequest bodyExamplesResponse bodyErrorsMore in Analytics
POST
/api/v1/projects/{projectId}/analytics/reports/metric-actors

Authorization

AuthorizationBearer <token>

A project secret key: vh_sk_... for production, vh_sk_test_... for test. Keep it on your servers.

In: header

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.

query*

One metric to measure over a time range.

bucketStart*string

The start of the point's bucket, as one of the result's buckets gives it, such as 2026-03-02T00:00:00.000Z.

group?|

A key of the result's series, $other and $unknown included, for that group's point; without it, the point of total.

isPrevious?|

Whether the point is the comparison period's beside bucketStart, of previousTotal or a group's previousValues: the bucket at the same position for previous_period, the one starting a year earlier for previous_year. The query needs a comparison. Defaults to false.

search?|

Only actors whose name, email, distinct id or key contains this, ignoring case; a group by its key or name property.

cursor?|

Where the page starts: the pageInfo.endCursor of the previous page. Omit it for the first page.

limit?|

How many actors to return, from 1 to 200. Defaults to 50.

Examples

curl -X POST "https://api.voidhash.com/api/v1/projects/proj_tz4a98xxat96iws9zmbrgj3a/analytics/reports/metric-actors" \  -H "Authorization: Bearer vh_sk_..." \  -H "Content-Type: application/json" \  -d '{    "query": {      "key": "workouts",      "metric": {        "kind": "event",        "eventName": "workout_completed",        "aggregation": "unique_people"      },      "timeRange": {        "preset": "custom",        "start": "2026-03-01T00:00:00.000Z",        "end": "2026-03-07T23:59:59.999Z"      },      "granularity": "day"    },    "bucketStart": "2026-03-02T00:00:00.000Z",    "limit": 2  }'
{  "actorKind": "person",  "groupType": null,  "valueKind": "events",  "currency": null,  "total": 41,  "data": [    {      "key": "person_h7d2k9m4x1c6v8b3n5q0w2e7",      "value": 3,      "person": {        "id": "person_h7d2k9m4x1c6v8b3n5q0w2e7",        "name": "Ada Lovelace",        "email": "ada@example.com",        "distinctId": "user_8231"      },      "group": null    },    {      "key": "anon_5f2c9e",      "value": 1,      "person": {        "id": null,        "name": null,        "email": null,        "distinctId": "anon_5f2c9e"      },      "group": null    }  ],  "pageInfo": {    "endCursor": "WzEsMSwiYW5vbl81ZjJjOWUiXQ",    "hasNextPage": true  }}

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