> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tell.rs/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Queries

> Query analytics data — metrics, breakdowns, comparisons, raw drill-down, and SQL.

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:

```bash theme={null}
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:

```bash theme={null}
# 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

```bash theme={null}
# 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) |

Top lists (`/metrics/events/top`, `/metrics/logs/top`, `/metrics/sessions/top`, and the `top_events` / `top_logs:<field>` metric keys) rank labels, so each entry is a label and its count, with no `date`:

```json theme={null}
{
  "points": [
    { "value": 1840.0, "dimension": "page_view" },
    { "value": 312.0, "dimension": "signup" }
  ],
  "total": 2152.0, "min": 312.0, "max": 1840.0, "avg": 1076.0
}
```

## First-time events

Count users whose first occurrence of an event falls within the query range. See [Events — First-time events](https://docs.tell.rs/analytics/events.md#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:**

```bash theme={null}
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:**

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](https://docs.tell.rs/analytics/events.md#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:**

```bash theme={null}
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:**

```json theme={null}
{
  "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:**

```bash theme={null}
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

```bash theme={null}
# Session volume
curl "https://your-tell-server/api/v1/metrics/sessions?range=30d"

# Session volume per day, broken down by device type
curl "https://your-tell-server/api/v1/metrics/sessions?range=30d&granularity=daily&breakdown=device_type"

# 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

```bash theme={null}
# 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`. `source` is the host or instance that sent the log: the client's configured source, usually the host name. The Rust SDK still lets a per-log `component` replace it, for compatibility only; put a module or tracing target in a log property instead, so `source` stays one value per host.

Filter on a field inside a JSON log body with `message.<path>`:

```bash theme={null}
curl -X POST "https://your-tell-server/api/v1/metrics/query" \
  -H "Content-Type: application/json" \
  -d '{"metric": "log_volume", "range": "7d",
       "filters": [{"field": "message.EventId", "operator": "in", "value": ["4624", "4625"]}]}'
```

The path reads the body's string value. A number in the body does not match a quoted value: `"EventId": "4624"` matches `4624`, `"EventId": 4624` does not.

## Infrastructure metrics

Query a metric the SDKs or agents send with the key `metric:<name>:<fn>`:

```bash theme={null}
curl -X POST "https://your-tell-server/api/v1/metrics/query" \
  -H "Content-Type: application/json" \
  -d '{"metric": "metric:http.latency:hp95", "range": "24h",
       "granularity": "hourly", "breakdown": "labels.route"}'
```

For gauges and counters, `<fn>` aggregates the point value: `avg` (default), `sum`, `min`, `max`, `rate`, `last`, `count`, `median`, `p50`, `p75`, `p90`, `p95`, `p99`.

A histogram point has no useful value; its data is the observation count, sum, and buckets. Use the histogram functions for it:

| `<fn>` | Per time bucket |
| - | - |
| `hmean` | Mean observation: observed sum / observed count. |
| `hp50`, `hp75`, `hp90`, `hp95`, `hp99` | Quantile from the bucket counts, interpolated linearly within the bucket that holds it, as Prometheus `histogram_quantile` does. A quantile that falls in the open-ended top bucket reports the highest finite bound. |

Cumulative histograms (the SDK default) count what was observed between consecutive points of each series (one source, service, and label set). A drop in the count is a restart: that point counts whole. The first point of each series in the range is its starting reading and adds nothing. Delta histograms count every point. A bucket with no observations has no point. Break down by `labels.<key>`, `service`, or `source`.

## Users and stickiness

```bash theme={null}
# 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](https://docs.tell.rs/analytics/events.md#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](#common-parameters). Default granularity is `weekly`.

**Example:**

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

**Response:**

```json theme={null}
{
  "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](https://docs.tell.rs/analytics/segments.md) 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:**

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

**Response:**

```json theme={null}
[
  {"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:**

```bash theme={null}
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):**

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

**Response (engagement segment):**

```json theme={null}
[
  {
    "device_id": "a1b2c3d4",
    "segment": "power_user",
    "session_count": 47
  }
]
```

## Formulas

Combine multiple metric series with a math expression. See [Events — Formulas](https://docs.tell.rs/analytics/events.md#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:**

```bash theme={null}
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:**

```json theme={null}
{
  "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](https://docs.tell.rs/analytics/events.md#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:**

```bash theme={null}
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:**

```json theme={null}
{
  "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](https://docs.tell.rs/analytics/funnels.md) 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:**

```bash theme={null}
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:**

```json theme={null}
{
  "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:**

```bash theme={null}
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](https://docs.tell.rs/analytics/retention.md) 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:**

```bash theme={null}
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:**

```json theme={null}
{
  "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](https://docs.tell.rs/analytics/audiences.md) for definition syntax and usage.

### GET /api/v1/audiences

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

```bash theme={null}
curl https://your-tell-server/api/v1/audiences \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"
```

**Response:**

```json theme={null}
{
  "items": [
    {
      "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"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0,
  "has_more": false
}
```

This is a [list response](https://docs.tell.rs/api/authentication.md#list-responses). Pass `limit` and `offset` to page.

### 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:**

```bash theme={null}
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:**

```json theme={null}
{
  "audience_id": "aud_x7k9m2",
  "count": 3842
}
```

## Marks

Timeline annotations that overlay on charts. See [Boards — Marks](https://docs.tell.rs/analytics/boards.md#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 | Page size. Default: `50`, max: `200`. |
| `offset` | integer | No | Rows to skip. Default: `0`. |

**Example:**

```bash theme={null}
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:**

```json theme={null}
{
  "items": [
    {
      "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"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0,
  "has_more": false
}
```

This is a [list response](https://docs.tell.rs/api/authentication.md#list-responses).

### 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](https://docs.tell.rs/analytics/filtering.md)) |

Raw endpoints add pagination:

| Parameter | Default | Description |
| - | - | - |
| `limit` | `100` | Max rows returned (up to 10,000) |
| `offset` | `0` | Rows to skip, newest first |
| `count_total` | `false` | Also return `total`, the match count across all pages (slower) |

A raw endpoint returns one page of rows:

```json theme={null}
{
  "items": [
    { "timestamp": "2025-01-31 12:00:00.000", "event_name": "purchase", "device_id": "…" }
  ],
  "limit": 100,
  "offset": 0,
  "has_more": true,
  "total": 4821
}
```

`has_more` says whether another page follows; request it with `offset` set to `offset + limit`. `total` is present only with `count_total=true`.

## SQL queries

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

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
# List available data sources (a list response with sources in `items`)
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](https://docs.tell.rs/api/boards.md) — save and visualize query results
* [Sharing](https://docs.tell.rs/api/sharing.md) — share metrics and boards publicly
* [SQL Analytics](https://docs.tell.rs/analytics/sql.md) — SQL query patterns and tips


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.