Data Queries

The query API powers Tell’s analytics. Use it to fetch active users, events, sessions, logs, and stickiness metrics — with breakdowns, comparisons, and raw drill-down. All endpoints require a JWT token and X-Workspace-ID header:

curl "https://your-tell-server/api/v1/metrics/dau?range=30d" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

Active users

Track daily, weekly, and monthly active users:

# Daily active users, last 30 days
curl "https://your-tell-server/api/v1/metrics/dau?range=30d"

# Weekly active users, broken down by country
curl "https://your-tell-server/api/v1/metrics/wau?range=90d&breakdown=country"

# Monthly active users, compared to previous period
curl "https://your-tell-server/api/v1/metrics/mau?range=30d&compare=previous"

Endpoint	Metric
`/metrics/dau`	Daily active users
`/metrics/wau`	Weekly active users
`/metrics/mau`	Monthly active users

Each endpoint also has a /raw variant (e.g. /metrics/dau/raw) that returns the underlying user-level data with pagination.

Events

# Event volume over time
curl "https://your-tell-server/api/v1/metrics/events?range=30d&granularity=daily"

# Top events by count
curl "https://your-tell-server/api/v1/metrics/events/top?range=7d"

# Break down an event by a property
curl "https://your-tell-server/api/v1/metrics/events/properties?event=purchase&property=plan&range=30d"

# Custom aggregation — total revenue
curl "https://your-tell-server/api/v1/metrics/events/custom?event=purchase&property=amount&metric=sum&range=30d"

Endpoint	What it returns
`/metrics/events`	Event count over time
`/metrics/events/top`	Most frequent events ranked by count
`/metrics/events/top/{name}/raw`	Raw data for a specific event
`/metrics/events/properties`	Property breakdown (requires `event` and `property` params)
`/metrics/events/custom`	Aggregation on a property — `sum`, `avg`, `min`, `max`, `count`
`/metrics/events/raw`	Raw event data
`/metrics/events/first-time`	First-time event users per period
`/metrics/events/per-actor`	Per-user event aggregation (avg, p90)

First-time events

Count users whose first occurrence of an event falls within the query range. See Events — First-time events for usage.

GET /api/v1/metrics/events/first-time

Parameters:

Parameter	Type	Required	Description
`event`	string	Yes	Event name to analyze.
`match_mode`	boolean	No	Default: `false`. When `true`, filter conditions apply to the historical scan (first-match mode).
`lookback_days`	integer	No	Limit historical scan to this many days. Omit for full history.
`range`	string	No	Time range. Default: `30d`.
`granularity`	string	No	Time bucketing. Default: `daily`.
`breakdown`	string	No	Break down by a field (e.g., `country`, `properties.plan`).
`compare`	string	No	`previous` or `yoy`.

Example:

curl "https://your-tell-server/api/v1/metrics/events/first-time?\
event=sign_up&range=30d&granularity=weekly" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

Response:

{
  "data": {
    "points": [
      {"date": "2025-02-03", "value": 42},
      {"date": "2025-02-10", "value": 38},
      {"date": "2025-02-17", "value": 55}
    ],
    "total": 135,
    "min": 38,
    "max": 55,
    "avg": 45
  }
}

With breakdown=country, each point includes a dimension field:

{
  "data": {
    "points": [
      {"date": "2025-02-03", "value": 28, "dimension": "US"},
      {"date": "2025-02-03", "value": 14, "dimension": "GB"}
    ]
  }
}

Per-actor metrics

Two-level aggregation: first per user, then across users. See Events — Per-actor metrics for usage.

GET /api/v1/metrics/events/per-actor

Parameters:

Parameter	Type	Required	Description
`event`	string	Yes	Event name to analyze.
`metric`	string	No	Outer aggregation function. Default: `avg`. Options: `avg`, `median`, `p50`, `p75`, `p90`, `p95`, `p99`, `min`, `max`, `sum`.
`property`	string	No	Property to aggregate per user (e.g., `properties.amount`). If omitted, counts events per user.
`range`	string	No	Time range. Default: `30d`.
`granularity`	string	No	Time bucketing. Default: `daily`.
`breakdown`	string	No	Break down by a field (e.g., `country`, `properties.plan`).

Example — average events per user:

curl "https://your-tell-server/api/v1/metrics/events/per-actor?\
event=page_view&metric=avg&range=30d&granularity=weekly" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

Response:

{
  "data": {
    "points": [
      {"date": "2025-02-03", "value": 4.5},
      {"date": "2025-02-10", "value": 5.2},
      {"date": "2025-02-17", "value": 4.8}
    ],
    "total": 14.5,
    "min": 4.5,
    "max": 5.2,
    "avg": 4.83
  }
}

Example — p90 revenue per user:

curl "https://your-tell-server/api/v1/metrics/events/per-actor?\
event=purchase&metric=p90&property=properties.amount&range=30d" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

Sessions

# Session volume
curl "https://your-tell-server/api/v1/metrics/sessions?range=30d"

# Top sessions by device type
curl "https://your-tell-server/api/v1/metrics/sessions/top?range=30d&property=device_type"

# Unique sessions
curl "https://your-tell-server/api/v1/metrics/sessions/unique?range=30d"

Logs

# Log volume over time
curl "https://your-tell-server/api/v1/metrics/logs?range=7d"

# Top logs by level
curl "https://your-tell-server/api/v1/metrics/logs/top?range=7d"

# Filter by service and level
curl "https://your-tell-server/api/v1/metrics/logs/raw?service=api&level=error&range=7d"

Log-specific filters: service, level, source.

Users and stickiness

# User count over time
curl "https://your-tell-server/api/v1/metrics/users?range=30d"

# Daily stickiness (DAU/MAU ratio)
curl "https://your-tell-server/api/v1/metrics/stickiness/daily?range=30d"

# Weekly stickiness (WAU/MAU ratio)
curl "https://your-tell-server/api/v1/metrics/stickiness/weekly?range=30d"

Lifecycle

Classify active users into lifecycle states over time. See Events — Lifecycle for usage.

GET /api/v1/metrics/lifecycle

Returns a time series with each active user classified as new, returning, or resurrected per period. Parameters: Standard common parameters. Default granularity is weekly. Example:

curl "https://your-tell-server/api/v1/metrics/lifecycle?range=30d&granularity=weekly" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

Response:

{
  "data": {
    "points": [
      {"date": "2025-02-03", "value": 150, "dimension": "new"},
      {"date": "2025-02-03", "value": 800, "dimension": "returning"},
      {"date": "2025-02-03", "value": 50, "dimension": "resurrected"}
    ],
    "total": 1000,
    "min": 50,
    "max": 800,
    "avg": 333
  }
}

Segments

Snapshot classification of all users into lifecycle and engagement segments. See Segments for definitions.

GET /api/v1/metrics/segments

Returns user counts for all 8 built-in segments. Parameters:

Parameter	Type	Required	Description
`range`	string	No	Time range for computation. Default: `30d`.

Example:

curl "https://your-tell-server/api/v1/metrics/segments?range=30d" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

Response:

[
  {"segment": "new", "category": "lifecycle", "users": 342},
  {"segment": "returning", "category": "lifecycle", "users": 1205},
  {"segment": "dormant", "category": "lifecycle", "users": 587},
  {"segment": "churned", "category": "lifecycle", "users": 2341},
  {"segment": "one_timer", "category": "engagement", "users": 891},
  {"segment": "casual", "category": "engagement", "users": 645},
  {"segment": "regular", "category": "engagement", "users": 412},
  {"segment": "power_user", "category": "engagement", "users": 189}
]

GET /api/v1/metrics/segments/:segment

Drill into a specific segment to see individual users. Parameters:

Parameter	Type	Required	Description
`range`	string	No	Time range. Default: `30d`.
`limit`	integer	No	Max users returned. Default: `50`, max: `100`.

Example:

curl "https://your-tell-server/api/v1/metrics/segments/dormant?range=90d&limit=20" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

Response (lifecycle segment):

[
  {
    "device_id": "a1b2c3d4",
    "segment": "dormant",
    "first_seen": "2025-01-10T08:30:00Z",
    "last_seen": "2025-02-05T14:22:00Z"
  }
]

Response (engagement segment):

[
  {
    "device_id": "a1b2c3d4",
    "segment": "power_user",
    "session_count": 47
  }
]

Formulas

Combine multiple metric series with a math expression. See Events — Formulas for syntax and usage.

POST /api/v1/metrics/formula

Evaluate a formula across multiple metric series. Request body:

Field	Type	Required	Description
`series`	array	Yes	Metric series to evaluate. Each has `metric` (string), optional `filters` (array), optional `breakdown` (string), optional `range` (string override).
`formula`	string	Yes	Math expression using series references A–Z.
`range`	string	No	Time range. Default: `30d`.
`granularity`	string	No	Time bucketing. Default: `daily`.

Series metric values: dau, wau, mau, events, event:<name>, sessions, users, logs. Example:

curl -X POST https://your-tell-server/api/v1/metrics/formula \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "series": [
      { "metric": "event:sign_up" },
      { "metric": "event:purchase" }
    ],
    "formula": "B / A * 100",
    "range": "30d",
    "granularity": "daily"
  }'

Response:

{
  "data": {
    "points": [
      { "date": "2025-06-01", "value": 16.2 },
      { "date": "2025-06-02", "value": 18.5 }
    ],
    "total": 17.1,
    "min": 12.0,
    "max": 22.4,
    "avg": 17.1
  }
}

Grouped metrics

Proportional composition with two metrics per group. See Events — Grouped metrics for usage.

POST /api/v1/metrics/grouped

Compute grouped metrics for treemap visualization. Request body:

Field	Type	Required	Description
`group_by`	string	Yes	Field to group by (e.g., `country`, `event_name`, `properties.plan`).
`size`	object	Yes	Size metric: `{ "type": "count" }`, `{ "type": "unique_actors" }`, or `{ "type": "sum", "property": "properties.revenue" }`.
`intensity`	object	Yes	Intensity metric: `{ "type": "avg_per_actor" }`, `{ "type": "percentile_per_actor", "percentile": 0.9 }`, `{ "type": "unique_actors" }`, or `{ "type": "avg", "property": "properties.load_time" }`.
`event`	string	No	Filter to a specific event.
`range`	string	No	Time range. Default: `30d`.
`max_groups`	integer	No	Max groups returned. Default: `20`.

Example:

curl -X POST https://your-tell-server/api/v1/metrics/grouped \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "group_by": "country",
    "size": { "type": "unique_actors" },
    "intensity": { "type": "avg_per_actor" },
    "range": "30d"
  }'

Response:

{
  "data": {
    "groups": [
      { "group": "US", "size": 1500, "intensity": 3.2, "children": [] },
      { "group": "CA", "size": 800, "intensity": 2.8, "children": [] },
      { "group": "UK", "size": 200, "intensity": 2.5, "children": [] }
    ],
    "total_size": 2500,
    "size_label": "User Count",
    "intensity_label": "Avg Events/User",
    "intensity_min": 2.5,
    "intensity_max": 3.2
  }
}

Funnels

Analyze step-by-step conversion. See the Funnels product guide for concepts and examples.

POST /api/v1/funnels

Run a funnel analysis across a sequence of events. Request body:

Field	Type	Required	Description
`steps`	array	Yes	2–10 funnel steps. Each step has `event` (string) and optional `filters` (array of conditions).
`window_seconds`	integer	No	Max seconds for a user to complete all steps. Default: `604800` (7 days).
`breakdown`	string	No	Split results by a dimension (e.g., `country`, `device_type`).
`range`	string	No	Time range. Default: `30d`.

Step filter fields:

Field	Type	Required	Description
`field`	string	Yes	Property to filter on (e.g., `properties.plan`).
`operator`	string	No	Comparison operator. Default: `eq`.
`value`	any	No	Value to compare against. String, number, or array (for `in`/`not_in`).

Example:

curl -X POST https://your-tell-server/api/v1/funnels \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "steps": [
      { "event": "sign_up" },
      { "event": "purchase" }
    ],
    "window_seconds": 604800,
    "range": "30d"
  }'

Response:

{
  "data": {
    "steps": [
      { "step": 1, "event": "sign_up",  "count": 1200, "overall_rate": 1.0,  "step_rate": 1.0, "drop_off": 0 },
      { "step": 2, "event": "purchase", "count": 192,  "overall_rate": 0.16, "step_rate": 0.16, "drop_off": 1008 }
    ],
    "overall_conversion": 0.16
  }
}

POST /api/v1/funnels/trend

Track funnel conversion rate over time. Same request body as POST /api/v1/funnels, plus a granularity field.

Field	Type	Required	Description
`granularity`	string	No	Time bucket size: `minute`, `hourly`, `daily`, `weekly`, `monthly`. Default: `daily`.

Example:

curl -X POST https://your-tell-server/api/v1/funnels/trend \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "steps": [
      { "event": "sign_up" },
      { "event": "purchase" }
    ],
    "window_seconds": 604800,
    "range": "30d",
    "granularity": "daily"
  }'

Returns time series data with conversion rate per time bucket.

Retention

Cohort retention analysis. See the Retention product guide for how to read the cohort matrix.

POST /api/v1/retention

Run a cohort retention analysis. Request body:

Field	Type	Required	Description
`granularity`	string	No	Cohort bucketing: `daily`, `weekly`, `monthly`. Default: `weekly`.
`periods`	integer	No	Number of periods to track (1–52). Default: `8`.
`start_event`	string	No	Cohort entry event. Default: any event.
`return_event`	string	No	Return activity event. Default: any event.
`range`	string	No	Time range. Default: `90d`.

Example:

curl -X POST https://your-tell-server/api/v1/retention \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "granularity": "weekly",
    "periods": 8,
    "start_event": "sign_up",
    "range": "90d"
  }'

Response:

{
  "data": {
    "cohorts": [
      {
        "cohort_date": "2025-04-07",
        "cohort_size": 320,
        "retention": [1.0, 0.45, 0.32, 0.28],
        "counts": [320, 144, 102, 90]
      }
    ],
    "averages": [1.0, 0.45, 0.32, 0.28],
    "granularity": "week",
    "periods": 8
  }
}

Audiences

Manage saved user groups. See the Audiences product guide for definition syntax and usage.

GET /api/v1/audiences

List all audiences in the workspace. Requires Viewer role or above.

curl https://your-tell-server/api/v1/audiences \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

Response:

{
  "data": {
    "audiences": [
      {
        "id": "aud_x7k9m2",
        "name": "US power buyers",
        "description": "US users who purchased in the last 30 days",
        "definition": { "filters": [...], "events": [...] },
        "created_at": "2025-06-15T10:30:00Z",
        "updated_at": "2025-06-15T10:30:00Z"
      }
    ]
  }
}

POST /api/v1/audiences

Create an audience. Requires Editor role or above. Request body:

Field	Type	Required	Description
`name`	string	Yes	Audience name (1–200 characters).
`description`	string	No	Description (max 2000 characters).
`definition`	object	Yes	Audience rules. Contains `filters` (array), `events` (array), and optional `lookback_days` (integer).

Example:

curl -X POST https://your-tell-server/api/v1/audiences \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US power buyers",
    "definition": {
      "filters": [
        { "field": "country", "operator": "eq", "value": "US" }
      ],
      "events": [
        { "event": "purchase", "days": 30 }
      ]
    }
  }'

GET /api/v1/audiences/:id

Get a single audience by ID.

PUT /api/v1/audiences/:id

Update an audience. Only the owner or a workspace admin can update. All fields are optional — omit a field to keep its current value. Request body:

Field	Type	Required	Description
`name`	string	No	New name.
`description`	string	No	New description.
`definition`	object	No	Updated audience rules.

DELETE /api/v1/audiences/:id

Delete an audience. Only the owner or a workspace admin can delete.

GET /api/v1/audiences/:id/count

Get the number of users matching an audience’s rules. Response:

{
  "data": {
    "audience_id": "aud_x7k9m2",
    "count": 3842
  }
}

Marks

Timeline annotations that overlay on charts. See Boards — Marks for product usage.

GET /api/v1/marks

List marks in the workspace. Public marks are visible to all members. Private marks are only visible to their creator. Query parameters:

Parameter	Type	Required	Description
`from`	string	No	Start time (ISO 8601).
`to`	string	No	End time (ISO 8601).
`category`	string	No	Filter by category: `release`, `news`, `incident`.
`source`	string	No	Filter by source: `manual`, `api`, `plugin`.
`limit`	integer	No	Max results. Default: `500`.

Example:

curl "https://your-tell-server/api/v1/marks?category=release&from=2025-06-01T00:00:00Z" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

Response:

{
  "data": {
    "marks": [
      {
        "id": "mrk_a1b2c3",
        "title": "Shipped v2.1.0",
        "description": null,
        "timestamp": "2025-06-15T14:30:00Z",
        "category": "release",
        "source": "manual",
        "source_ref": "https://github.com/example/repo/releases/tag/v2.1.0",
        "scope": "public",
        "created_by": "usr_abc",
        "created_at": "2025-06-15T14:30:00Z",
        "updated_at": "2025-06-15T14:30:00Z"
      }
    ]
  }
}

GET /api/v1/marks/:id

Get a single mark by ID. Returns 404 for private marks belonging to other users.

POST /api/v1/marks

Create a mark. Requires Editor role or above. Request body:

Field	Type	Required	Description
`title`	string	Yes	Mark title (1–200 characters).
`description`	string	No	Description (max 2000 characters).
`timestamp`	string	No	When the event happened (ISO 8601). Default: now.
`category`	string	No	`release`, `news`, or `incident`. Default: `release`.
`source_ref`	string	No	URL, commit SHA, or other reference.
`scope`	string	No	`public` or `private`. Default: `public`.
`metadata`	string	No	JSON blob (max 10KB).

DELETE /api/v1/marks/:id

Delete a mark. Only the creator or a workspace admin can delete.

Common parameters

Most metric endpoints share these query parameters:

Parameter	Default	Options
`range`	`30d`	`7d`, `30d`, `90d`, or custom: `2025-01-01,2025-01-31`
`granularity`	`daily`	`minute`, `hourly`, `daily`, `weekly`, `monthly`
`breakdown`	—	Any dimension: `country`, `platform`, `device_type`, `os`, etc.
`compare`	—	`previous` (previous period) or `yoy` (year-over-year)
`conditions[N][field]`	—	Filter conditions (see Filtering)

Raw endpoints add pagination:

Parameter	Default	Description
`limit`	`100`	Max rows returned
`offset`	`0`	Skip rows for pagination
`count_total`	`false`	Include total count (slower)

SQL queries

For full flexibility, execute SQL directly against your analytics data. Rate-limited to 30 requests per minute.

curl -X POST https://your-tell-server/api/v1/data/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT event, count() as cnt FROM events_v1 GROUP BY event ORDER BY cnt DESC LIMIT 10"}'

Returns:

{
  "columns": [
    { "name": "event", "data_type": "String" },
    { "name": "cnt", "data_type": "UInt64" }
  ],
  "rows": [
    ["page_view", 48210],
    ["click", 12503]
  ],
  "row_count": 2,
  "execution_time_ms": 42
}

Only SELECT statements are allowed. Queries are automatically scoped to your workspace database. Max 10,000 rows per query (default 1,000).

Data exploration

Discover what data is available before writing queries:

# List available data sources
curl https://your-tell-server/api/v1/data/sources \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

# Get fields for a source
curl https://your-tell-server/api/v1/data/sources/events/fields \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

# Get distinct values for a field
curl "https://your-tell-server/api/v1/data/sources/events/values/country?limit=20" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

Available sources

Source	Table	Description
`events`	events_v1	Custom events and page views
`logs`	logs_v1	Structured logs
`context`	context_v1	Device and session context
`user_traits`	user_traits_v1	User properties set via `identify`
`users`	users_v1	Unique users
`user_devices`	user_devices	Device-to-user mappings

What’s next

Boards & Metrics — save and visualize query results
Sharing — share metrics and boards publicly
SQL Analytics — SQL query patterns and tips

​Active users

​Events

​First-time events

​GET /api/v1/metrics/events/first-time

​Per-actor metrics

​GET /api/v1/metrics/events/per-actor

​Sessions

​Logs

​Users and stickiness

​Lifecycle

​GET /api/v1/metrics/lifecycle

​Segments

​GET /api/v1/metrics/segments

​GET /api/v1/metrics/segments/:segment

​Formulas

​POST /api/v1/metrics/formula

​Grouped metrics

​POST /api/v1/metrics/grouped

​Funnels

​POST /api/v1/funnels

​POST /api/v1/funnels/trend

​Retention

​POST /api/v1/retention

​Audiences

​GET /api/v1/audiences

​POST /api/v1/audiences

​GET /api/v1/audiences/:id

​PUT /api/v1/audiences/:id

​DELETE /api/v1/audiences/:id

​GET /api/v1/audiences/:id/count

​Marks

​GET /api/v1/marks

​GET /api/v1/marks/:id

​POST /api/v1/marks

​DELETE /api/v1/marks/:id

​Common parameters

​SQL queries

​Data exploration

​Available sources

​What’s next

Active users

Events

First-time events

GET /api/v1/metrics/events/first-time

Per-actor metrics

GET /api/v1/metrics/events/per-actor

Sessions

Logs

Users and stickiness

Lifecycle

GET /api/v1/metrics/lifecycle

Segments

GET /api/v1/metrics/segments

GET /api/v1/metrics/segments/:segment

Formulas

POST /api/v1/metrics/formula

Grouped metrics

POST /api/v1/metrics/grouped

Funnels

POST /api/v1/funnels

POST /api/v1/funnels/trend

Retention

POST /api/v1/retention

Audiences

GET /api/v1/audiences

POST /api/v1/audiences

GET /api/v1/audiences/:id

PUT /api/v1/audiences/:id

DELETE /api/v1/audiences/:id

GET /api/v1/audiences/:id/count

Marks

GET /api/v1/marks

GET /api/v1/marks/:id

POST /api/v1/marks

DELETE /api/v1/marks/:id

Common parameters

SQL queries

Data exploration

Available sources

What’s next