> ## 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)                           |

## First-time events

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

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

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

```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}
{
  "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:**

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

# 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`.

## 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](/analytics/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](#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}
{
  "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](/analytics/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:**

```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](/analytics/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:**

```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}
{
  "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](/analytics/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:**

```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}
{
  "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](/analytics/funnels) 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}
{
  "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:**

```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](/analytics/retention) 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}
{
  "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](/analytics/audiences) 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}
{
  "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:**

```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}
{
  "data": {
    "audience_id": "aud_x7k9m2",
    "count": 3842
  }
}
```

## Marks

Timeline annotations that overlay on charts. See [Boards — Marks](/analytics/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:**

```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}
{
  "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](/analytics/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**.

```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
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](/api/boards) — save and visualize query results
* [Sharing](/api/sharing) — share metrics and boards publicly
* [SQL Analytics](/analytics/sql) — SQL query patterns and tips