Compute insights

Computes up to 20 of the built-in insights (revenue, MRR, churn, trials, persons, retention and more) over a time range, each with an optional filter, breakdown and granularity.

Each result carries the caller's key and the absolute time range it covered. A monetary insight reports in the organization's reporting currency (USD until one is chosen in its settings), names it in summary.currency, and gives its amounts in integer minor units of it, such as cents. A secret key reports its own environment's events and revenue; a person's own credentials choose with x-environment: production (the default), test or all.

Guide: Analytics overview

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.

queries*array<>

The insights to compute, 1 to 20. Results come back in the same order.

Items1 <= items <= 20

Examples

curl -X POST "https://api.voidhash.com/api/v1/projects/proj_tz4a98xxat96iws9zmbrgj3a/analytics/reports/insights" \  -H "Authorization: Bearer vh_sk_..." \  -H "Content-Type: application/json" \  -d '{    "queries": [      {        "key": "mrr",        "insightId": "mrr",        "timeRange": {          "preset": "custom",          "start": "2026-01-01T00:00:00.000Z",          "end": "2026-04-01T00:00:00.000Z"        },        "granularity": "month"      }    ]  }'

{  "results": [    {      "insightId": "mrr",      "key": "mrr",      "resolvedTimeRange": {        "start": "2026-01-01T00:00:00.000Z",        "end": "2026-04-01T00:00:00.000Z"      },      "result": {        "kind": "metric",        "sparkline": [          {            "timestamp": "2026-01-01T00:00:00.000Z",            "value": 1182400          },          {            "timestamp": "2026-02-01T00:00:00.000Z",            "value": 1241900          },          {            "timestamp": "2026-03-01T00:00:00.000Z",            "value": 1288350          }        ],        "summary": {          "currency": "USD",          "value": 1288350        }      }    }  ]}

{  "error": {    "type": "invalid_request",    "code": "unknown_insight",    "message": "Unknown analytics insight churn_rate",    "param": "queries"  }}

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

Errors

Status	`type`	`code`	When
400	`invalid_request`	`unknown_insight`	With a message saying what to change.
400	`invalid_request`	`unsupported_filter`	With a message saying what to change.
400	`invalid_request`	`unsupported_breakdown`	With a message saying what to change.
400	`invalid_request`	`invalid_time_range`	With a message saying what to change.
400	`invalid_request`	`invalid_report_request`	With a message saying what to change.

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

More in Analytics

Guide: Analytics overview

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.

queries*array<>

The insights to compute, 1 to 20. Results come back in the same order.

Items1 <= items <= 20

Examples

curl -X POST "https://api.voidhash.com/api/v1/projects/proj_tz4a98xxat96iws9zmbrgj3a/analytics/reports/insights" \  -H "Authorization: Bearer vh_sk_..." \  -H "Content-Type: application/json" \  -d '{    "queries": [      {        "key": "mrr",        "insightId": "mrr",        "timeRange": {          "preset": "custom",          "start": "2026-01-01T00:00:00.000Z",          "end": "2026-04-01T00:00:00.000Z"        },        "granularity": "month"      }    ]  }'

{  "results": [    {      "insightId": "mrr",      "key": "mrr",      "resolvedTimeRange": {        "start": "2026-01-01T00:00:00.000Z",        "end": "2026-04-01T00:00:00.000Z"      },      "result": {        "kind": "metric",        "sparkline": [          {            "timestamp": "2026-01-01T00:00:00.000Z",            "value": 1182400          },          {            "timestamp": "2026-02-01T00:00:00.000Z",            "value": 1241900          },          {            "timestamp": "2026-03-01T00:00:00.000Z",            "value": 1288350          }        ],        "summary": {          "currency": "USD",          "value": 1288350        }      }    }  ]}

{  "error": {    "type": "invalid_request",    "code": "unknown_insight",    "message": "Unknown analytics insight churn_rate",    "param": "queries"  }}

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

Errors

Status	`type`	`code`	When
400	`invalid_request`	`unknown_insight`	With a message saying what to change.
400	`invalid_request`	`unsupported_filter`	With a message saying what to change.
400	`invalid_request`	`unsupported_breakdown`	With a message saying what to change.
400	`invalid_request`	`invalid_time_range`	With a message saying what to change.
400	`invalid_request`	`invalid_report_request`	With a message saying what to change.

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

unknown_insight

unsupported_filter

unsupported_breakdown

invalid_time_range

invalid_report_request

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

Compute insights

unknown_insight

unsupported_filter

unsupported_breakdown

invalid_time_range

invalid_report_request

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`