v1.

0
Analytics & Metrics API
[Link]

Ingest events, query aggregated metrics, and export raw event logs. Built on a column-oriented store with
sub-second query latency for datasets up to 100 billion events.

On This Page
●
Authentication
●
Endpoints overview
●
Ingest and query events
●
Query metrics, funnels, and retention
●
Schedule and download reports
●
Metric Catalog
●
Data Retention & Sampling
●
Rate Limits & Quotas
●
Error Codes
●
Versioning & Changelog
●
SDKs & Client Libraries

Authentication
All requests must include an Authorization: Bearer <token> header. Write tokens (used for POST
/v1/events) and read tokens (used for querying metrics and reports) are managed separately under
Settings → API Keys.

Authorization: Bearer an_live_6tH2...pQ9x

Endpoints
POST /v1/events
Ingest one or more events

GET /v1/events
Query raw events with filters

GET /v1/metrics/{metric}
Retrieve an aggregated metric

GET /v1/funnels/{funnel_id}
Get funnel conversion data

POST /v1/funnels
Define a new funnel
GET /v1/retention
Cohort retention analysis

POST /v1/reports
Schedule an async report export

GET /v1/reports/{report_id}
Poll or download a scheduled report

POST /v1/events — Ingest Events

Accepts a single event object or an array of up to 5,000 events per request. Events are processed
asynchronously; delivery is guaranteed within 60 seconds.

Event Object Fields

Parameter Type Required Description

event string Yes Event name, e.g. page_view, purchase, sign_up

user_id string No Internal user identifier for cross-device stitching

anonymous_id string No Session or device ID for anonymous users

properties object No Arbitrary key-value pairs describing the event

timestamp string No ISO 8601 timestamp; defaults to server time

context object No Device, locale, IP, and campaign attribution

Example Request
POST /v1/events

[
{
"event": "purchase",
"user_id": "usr_7Hk2mP9qR",
"properties": {
"product_id": "prod_xZ4",
"revenue": 49.99,
"currency": "USD"
},
"timestamp": "2026-06-10T14:32:00Z"
}
]

Code Samples
cURL
curl -X POST \
"[Link] \
-H "Authorization: Bearer $API_KEY" \
 -H "Content-Type: application/json" \
-d '[
{
"event": "purchase",
"user_id": "usr_7Hk2mP9qR",
"properties": {
"product_id": "prod_xZ4",
"revenue": 49.99,
"currency": "USD"
},
"timestamp": "2026-06-10T14:32:00Z"
}
]'
Python
import requests

url = "[Link]
headers = {"Authorization": f"Bearer {API_KEY}"}
payload = [
{
"event": "purchase",
"user_id": "usr_7Hk2mP9qR",
"properties": {
"product_id": "prod_xZ4",
"revenue": 49.99,
"currency": "USD"
},
"timestamp": "2026-06-10T14:32:00Z"
}
]
resp = [Link](url, headers=headers, json=payload)
print([Link]())
[Link]
const res = await fetch("[Link] {
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: [Link]([{"event": "purchase", "user_id": "usr_7Hk2mP9qR",
"properties": {"product_id": "prod_xZ4", "revenue": 49.99, "currency": "USD"},
"timestamp": "2026-06-10T14:32:00Z"}]),
});
const data = await [Link]();

Response Fields
Field Type Description

accepted integer Number of events accepted for processing

rejected integer Number of events rejected for validation errors

request_id string Identifier for this ingestion request, useful for support requests

Example Response
{
"accepted": 1,
"rejected": 0,
"request_id": "req_3xPq9KbZmN"
}

GET /v1/events — Query Raw Events

Returns raw event records matching the given filters. Intended for debugging and ad-hoc analysis — for
dashboards, prefer the metrics endpoints.

Query Parameters
Parameter Type Required Description

event string No Filter by event name

user_id string No Filter by internal user ID

start string Yes Start of time range, ISO 8601 or relative (e.g. -7d)

end string Yes End of time range

limit integer No Max number of results (default 100, max 1000)

Code Samples
cURL
curl -X GET \
"[Link]
6-10T09:00:00Z" \
-H "Authorization: Bearer $API_KEY"
Python
import requests

url = "[Link]
26-06-10T09:00:00Z"
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = [Link](url, headers=headers)
print([Link]())
[Link]
const res = await fetch("[Link]
0T09:00:00Z&end=2026-06-10T09:00:00Z", {
method: "GET",
headers: { Authorization: `Bearer ${API_KEY}` },
});
const data = await [Link]();
Response Fields
Field Type Description

event string Event name

user_id string Internal user identifier

properties object Arbitrary key-value pairs describing the event

timestamp string ISO 8601 timestamp of when the event occurred

Example Response
{
"data": [
{
"event": "purchase",
"user_id": "usr_7Hk2mP9qR",
"properties": {
"key": "value"
},
"timestamp": "2026-06-10T09:00:00Z"
}
],
"meta": {
"total": 1,
"page": 1,
"per_page": 20
}
}

GET /v1/metrics/{metric} — Query Metric

Returns time-series data for a built-in or custom metric, bucketed by the requested interval.

Path Parameters
Field Type Description

metric string Metric slug, e.g. dau, mau, revenue, conversion_rate

Query Parameters
Parameter Type Required Description

start string Yes Start of time range, ISO 8601 or relative (e.g. -30d)

end string Yes End of time range

interval string No Aggregation bucket: hour, day (default), week, month

segment_by string No Property name to break the metric down by

filter string No RSQL filter expression, e.g. country==US

Code Samples
cURL
curl -X GET \
"[Link]
nd=2026-06-10T09:00:00Z" \
-H "Authorization: Bearer $API_KEY"
Python
import requests

url = "[Link]
0Z&end=2026-06-10T09:00:00Z"
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = [Link](url, headers=headers)
print([Link]())
[Link]
const res = await fetch("[Link]
2026-06-10T09:00:00Z&end=2026-06-10T09:00:00Z", {
method: "GET",
headers: { Authorization: `Bearer ${API_KEY}` },
});
const data = await [Link]();

Response Fields
Field Type Description

metric string Metric slug that was queried

interval string Aggregation bucket used

data array Array of {date, value} points

Example Response
{
"metric": "revenue",
"interval": "day",
"data": [
{
"date": "2026-06-01",
"value": 18234.5
},
{
"date": "2026-06-02",
"value": 21042.1
},
{
"date": "2026-06-03",
"value": 19850.75
}
 ]
}

GET /v1/funnels/{funnel_id} — Get Funnel

Returns conversion data for a previously defined funnel, including the drop-off at each step.

Path Parameters
Field Type Description

funnel_id string Unique identifier of the funnel

Code Samples
cURL
curl -X GET \
"[Link] \
-H "Authorization: Bearer $API_KEY"
Python
import requests

url = "[Link]
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = [Link](url, headers=headers)
print([Link]())
[Link]
const res = await
fetch("[Link] {
method: "GET",
headers: { Authorization: `Bearer ${API_KEY}` },
});
const data = await [Link]();

Response Fields
Field Type Description

id string Unique identifier of the funnel

name string Human-readable funnel name

steps array Ordered event names making up the funnel

conversion_rate number Overall conversion rate from first to last step

Example Response
{
"id": "fun_8mTq2Z1cVb",
"name": "Signup to Purchase",
"steps": [
 "sign_up",
"add_to_cart",
"purchase"
],
"conversion_rate": 0.184
}

POST /v1/funnels — Define Funnel

Creates a named, reusable funnel definition that can be queried via GET /v1/funnels/{funnel_id}.

Request Body
Parameter Type Required Description

name string Yes Human-readable funnel name

steps array Yes Ordered array of event names representing each funnel step

filters object No Optional property filters applied to all steps

Example Request
POST /v1/funnels

{
"name": "Signup to Purchase",
"steps": [
"sign_up",
"add_to_cart",
"purchase"
],
"filters": {
"country": "US"
}
}

Code Samples
cURL
curl -X POST \
"[Link] \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Signup to Purchase",
"steps": [
"sign_up",
"add_to_cart",
"purchase"
],
"filters": {
"country": "US"
 }
}'
Python
import requests

url = "[Link]
headers = {"Authorization": f"Bearer {API_KEY}"}
payload = {
"name": "Signup to Purchase",
"steps": [
"sign_up",
"add_to_cart",
"purchase"
],
"filters": {
"country": "US"
}
}
resp = [Link](url, headers=headers, json=payload)
print([Link]())
[Link]
const res = await fetch("[Link] {
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: [Link]({"name": "Signup to Purchase", "steps": ["sign_up",
"add_to_cart", "purchase"], "filters": {"country": "US"}}),
});
const data = await [Link]();

Response Fields
Field Type Description

id string Unique identifier assigned to the funnel

name string Human-readable funnel name

steps array Ordered event names making up the funnel

created_at string ISO 8601 timestamp of when the funnel was created

Example Response
{
"id": "fun_8mTq2Z1cVb",
"name": "Signup to Purchase",
"steps": [
"sign_up",
"add_to_cart",
"purchase"
 ],
"created_at": "2026-06-10T09:00:00Z"
}

GET /v1/retention — Cohort Retention

Groups users into cohorts based on cohort_event and reports the fraction of each cohort that
performed return_event in subsequent intervals.

Query Parameters
Parameter Type Required Description

start string Yes Start of the cohort window, ISO 8601 or relative (e.g. -90d)

end string Yes End of the cohort window

cohort_event string Yes Event that defines cohort entry, e.g. sign_up

return_event string Yes Event that defines a returning user, e.g. session_start

interval string No day, week (default), or month

Code Samples
cURL
curl -X GET \
"[Link]
6-06-10T09:00:00Z&cohort_event=sign_up&return_event=session_start" \
-H "Authorization: Bearer $API_KEY"
Python
import requests

url = "[Link]
=2026-06-10T09:00:00Z&cohort_event=sign_up&return_event=session_start"
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = [Link](url, headers=headers)
print([Link]())
[Link]
const res = await fetch("[Link]
6-10T09:00:00Z&end=2026-06-10T09:00:00Z&cohort_event=sign_up&return_event=session_st
art", {
method: "GET",
headers: { Authorization: `Bearer ${API_KEY}` },
});
const data = await [Link]();

Response Fields
Field Type Description

cohorts array Array of cohort retention rows

Example Response
{
"cohorts": [
{
"cohort": "2026-05-04",
"size": 1042,
"retention": [
1.0,
0.42,
0.31,
0.27
]
},
{
"cohort": "2026-05-11",
"size": 987,
"retention": [
1.0,
0.39,
0.29,
null
]
}
]
}

POST /v1/reports — Schedule Report

Schedules an asynchronous export of events, funnels, retention, or a custom query. Use GET
/v1/reports/{report_id} to poll for completion.

Request Body
Parameter Type Required Description

type string Yes Report type: events, funnels, retention, or custom

format string No csv (default) or json

filters object No Filters applied to the underlying query

delivery_email string No Email address to notify when the report is ready

Example Request
POST /v1/reports

{
"type": "email",
"format": "email",
"filters": {
"key": "value"
 },
"delivery_email": "alice@[Link]"
}

Code Samples
cURL
curl -X POST \
"[Link] \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "email",
"format": "email",
"filters": {
"key": "value"
},
"delivery_email": "alice@[Link]"
}'
Python
import requests

url = "[Link]
headers = {"Authorization": f"Bearer {API_KEY}"}
payload = {
"type": "email",
"format": "email",
"filters": {
"key": "value"
},
"delivery_email": "alice@[Link]"
}
resp = [Link](url, headers=headers, json=payload)
print([Link]())
[Link]
const res = await fetch("[Link] {
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: [Link]({"type": "email", "format": "email", "filters": {"key":
"value"}, "delivery_email": "alice@[Link]"}),
});
const data = await [Link]();

Response Fields
Field Type Description

report_id string Unique identifier for the scheduled report

status string pending, processing, completed, or failed

requested_at string ISO 8601 timestamp of when the report was requested

Example Response
{
"report_id": "rep_3xPq9KbZmN",
"status": "pending",
"requested_at": "2026-06-10T09:00:00Z"
}

GET /v1/reports/{report_id} — Poll or Download Report

Returns the status of a scheduled report. Once status is completed, download_url is a time-limited
link to the generated file.

Path Parameters
Field Type Description

report_id string Unique identifier of the scheduled report

Code Samples
cURL
curl -X GET \
"[Link] \
-H "Authorization: Bearer $API_KEY"
Python
import requests

url = "[Link]
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = [Link](url, headers=headers)
print([Link]())
[Link]
const res = await
fetch("[Link] {
method: "GET",
headers: { Authorization: `Bearer ${API_KEY}` },
});
const data = await [Link]();

Response Fields
Field Type Description

report_id string Unique identifier of the report

status string pending, processing, completed, or failed

download_url string Time-limited URL to download the report file

expires_at string ISO 8601 timestamp of when download_url expires

Example Response
{
"report_id": "rep_3xPq9KbZmN",
"status": "completed",
"download_url": "[Link]
"expires_at": "2026-06-10T09:00:00Z"
}

Note: Download links expire after 24 hours. Re-request the report to generate a new link.

Metric Catalog
The following built-in metrics are available to every project. Custom metrics defined in the dashboard can
be queried using the slug shown there.

Metric Description Unit

dau Distinct users active in the bucket users

mau Distinct users active in the trailing 30 days users

revenue Sum of the revenue property on purchase events currency

conversion_rate Purchases divided by sessions ratio

session_duration_p50 Median session duration seconds

retention_d7 Share of new users returning after 7 days ratio

Data Retention & Sampling

Raw events are retained for 13 months. Queries over windows longer than 90 days are automatically
sampled at 10% to maintain sub-second latency; sampled responses include "sampled": true and a
sample_rate field. Disable sampling for a single request with ?sampling=false, which may increase
latency for large date ranges.

Rate Limits & Quotas

Plan Ingestion Query rate

Starter 1M events/day 60 req/min

Growth 50M events/day 300 req/min

Enterprise Custom Custom

Error Codes
Code HTTP Status Description

invalid_request 400 Missing or malformed parameters

authentication_error 401 Invalid or missing API key

not_found 404 Funnel or report does not exist

payload_too_large 413 Event batch exceeds 5,000 events or 5 MB

rate_limit_exceeded 429 Too many requests, retry after the Retry-After header

server_error 500 Internal server error — contact support

Versioning & Changelog

Version Date Changes

v1.0 2026-01-15 Initial public release

v0.9 2025-10-02 Beta: added retention and report scheduling endpoints

v0.5 2025-05-20 Beta: added funnel definitions

SDKs & Client Libraries

Language Package Install

Python analytics-python pip install analytics-sdk

[Link] @analytics/node npm install @analytics/node

Java analytics-java implementation '[Link]:sdk:1.0.0'

Go go-analytics go get [Link]/analytics/go-sdk