> Public product help. This page has no customer entries, projects, chat transcripts, API keys, or horizon contents.
> Reading that data requires `Authorization: Bearer` (a signed-in app session JWT, or a Headless access token).
> Do not call Supabase `/rest/v1` with a Headless JWT. Data reads go through `/casc/v1/headless/v1/rest`.

# Analytics Tools

Analytics tools (`tool_kind: analytics`) let agents query structured JSON on entries with SQL-like aggregations. Aggregations read approved entry fields directly — they do **not** use vector embeddings.

> **Do not skip embedding for the whole pipeline.** Analytics itself does not need embeddings, but
> **search tools** on the same groups do. After ingesting or syncing data, still run
> **Initiate Embedding** (or enable Auto-embed) on linked *search* tools before significant
> LLM chat or workflows that rely on semantic search. See [tools](tools.md).

## When to use analytics vs search

| Need | Tool kind |
| --- | --- |
| Find similar text, documents, descriptions | **Search** (requires embeddings after ingest) |
| All rows where a field equals a value (exact recall) | **Filter** (see [filter](filter.md)) |
| Sum revenue, count tickets, group by region | **Analytics** (no embeddings for the aggregate itself) |
| Current events on the web | **Web search** |

## Data shape

Store metrics as JSON on a raw field, e.g. `raw.metrics` or an array of records in `raw.line_items`. Entries must be **approved** in linked ingestion groups.

## Query shape

Agents send a JSON query object:

```
{
  "query": {
    "measures": [{ "field": "amount", "op": "sum", "as": "total" }],
    "group_by": ["region"],
    "filters": [{ "field": "year", "op": "eq", "value": 2025 }],
    "order_by": [{ "field": "total", "dir": "desc" }],
    "limit": 20
  }
}
```

Supported measure ops typically include `sum`, `count`, `avg`, `min`, `max`. Filters support equality and comparison operators.

## Setup checklist

1. Ingestion group with JSON in mapped raw fields.
2. Approve entries in Data Review.
3. **Settings → Tools → Add** — kind Analytics, link groups, set **return fields** to allowlisted keys agents may read.
4. Set **search field** to the JSON field or primary return field.
5. If you also use **search** tools on these groups, **Initiate Embedding** after ingest before relying on semantic search in chat.
6. Attach tool to a prompt or rely on project global allowlist.
7. Test from project chat with a question that requires aggregation.

## Security model

Only fields listed in **return fields** are exposed to the analytics engine. Do not allowlist sensitive keys you do not want agents to aggregate.