---
title: "Run an analytics query"
method: POST
path: "/v1/projects/{projectSlug}/analytics/query"
tags: ["Analytics"]
---

# Run an analytics query

`POST /v1/projects/{projectSlug}/analytics/query`

Compute a metric over a filtered stream (`traces`/`sessions`/`spans`), optionally broken down by a dimension and/or bucketed over time. Returns a tidy series — one point per breakdown value and/or time bucket — suitable for charts and dashboards.

## Path parameters

- `projectSlug` string, required — Project slug (human-readable identifier)

## Request body

- union
  - object
    - `stream` 'traces', required
    - `query` string — Semantic search query, combined with `filters` via AND. Ranks/filters by relevance.
    - `breakdown` 'model' | 'provider' | 'service' | 'tool' | 'tag' | 'name' | 'userId' | 'status' — Dimension to group by, one row per value.
    - `metric` union, required — The metric: `count`, `errorRate`, `cacheHitRate`, `{sum|min|max|avg|median}` over `duration`/`cost`/`tokens`, or `{kind:'percentile',field,p}` for an arbitrary percentile (`p` in [1,99]; e.g. `p:95`).
      - object
        - `kind` 'count', required
      - object
        - `kind` 'errorRate', required
      - object
        - `kind` 'cacheHitRate', required
      - object
        - `kind` 'sum', required
        - `field` 'duration' | 'cost' | 'tokens', required
      - object
        - `kind` 'min', required
        - `field` 'duration' | 'cost' | 'tokens', required
      - object
        - `kind` 'max', required
        - `field` 'duration' | 'cost' | 'tokens', required
      - object
        - `kind` 'avg', required
        - `field` 'duration' | 'cost' | 'tokens', required
      - object
        - `kind` 'median', required
        - `field` 'duration' | 'cost' | 'tokens', required
      - object
        - `kind` 'percentile', required
        - `field` 'duration' | 'cost' | 'tokens', required
        - `p` number, required
    - `timeBucket` object — Bucket the metric over time. Omit for a single aggregate.
      - `unit` 'hour' | 'day' | 'week', required — Bucket granularity.
      - `size` integer — Number of units per bucket (e.g. `2` weeks).
    - `range` object, required — The time window.
      - `fromIso` string, date-time, required — Inclusive lower bound (ISO-8601).
      - `toIso` string, date-time, required — Exclusive upper bound (ISO-8601). Must be after `fromIso`.
    - `orderBy` object — Sort for breakdown results. Defaults to value-desc.
      - `by` 'value' | 'key'
      - `direction` 'asc' | 'desc'
    - `limit` integer — Maximum rows returned. Defaults to 50; max 500.
    - `filters` object — Structured filter set applied to the stream (same DSL as `listTraces`).
  - object
    - `stream` 'sessions', required
    - `query` string — Semantic search query, combined with `filters` via AND. Ranks/filters by relevance.
    - `breakdown` 'model' | 'provider' | 'service' | 'tool' | 'tag' | 'userId' | 'status' — Dimension to group by, one row per value.
    - `metric` union, required — The metric: `count`, `errorRate`, `cacheHitRate`, `{sum|min|max|avg|median}` over `duration`/`cost`/`tokens`, or `{kind:'percentile',field,p}` for an arbitrary percentile (`p` in [1,99]; e.g. `p:95`).
      - object
        - `kind` 'count', required
      - object
        - `kind` 'errorRate', required
      - object
        - `kind` 'cacheHitRate', required
      - object
        - `kind` 'sum', required
        - `field` 'duration' | 'cost' | 'tokens', required
      - object
        - `kind` 'min', required
        - `field` 'duration' | 'cost' | 'tokens', required
      - object
        - `kind` 'max', required
        - `field` 'duration' | 'cost' | 'tokens', required
      - object
        - `kind` 'avg', required
        - `field` 'duration' | 'cost' | 'tokens', required
      - object
        - `kind` 'median', required
        - `field` 'duration' | 'cost' | 'tokens', required
      - object
        - `kind` 'percentile', required
        - `field` 'duration' | 'cost' | 'tokens', required
        - `p` number, required
    - `timeBucket` object — Bucket the metric over time. Omit for a single aggregate.
      - `unit` 'hour' | 'day' | 'week', required — Bucket granularity.
      - `size` integer — Number of units per bucket (e.g. `2` weeks).
    - `range` object, required — The time window.
      - `fromIso` string, date-time, required — Inclusive lower bound (ISO-8601).
      - `toIso` string, date-time, required — Exclusive upper bound (ISO-8601). Must be after `fromIso`.
    - `orderBy` object — Sort for breakdown results. Defaults to value-desc.
      - `by` 'value' | 'key'
      - `direction` 'asc' | 'desc'
    - `limit` integer — Maximum rows returned. Defaults to 50; max 500.
    - `filters` object — Structured filter set applied to the stream (same DSL as `listTraces`).
  - object
    - `stream` 'spans', required
    - `breakdown` 'model' | 'provider' | 'service' | 'tool' | 'tag' | 'operation' | 'status' — Dimension to group by, one row per value.
    - `metric` union, required — The metric: `count`, `errorRate`, `cacheHitRate`, `{sum|min|max|avg|median}` over `duration`/`cost`/`tokens`, or `{kind:'percentile',field,p}` for an arbitrary percentile (`p` in [1,99]; e.g. `p:95`).
      - object
        - `kind` 'count', required
      - object
        - `kind` 'errorRate', required
      - object
        - `kind` 'cacheHitRate', required
      - object
        - `kind` 'sum', required
        - `field` 'duration' | 'cost' | 'tokens', required
      - object
        - `kind` 'min', required
        - `field` 'duration' | 'cost' | 'tokens', required
      - object
        - `kind` 'max', required
        - `field` 'duration' | 'cost' | 'tokens', required
      - object
        - `kind` 'avg', required
        - `field` 'duration' | 'cost' | 'tokens', required
      - object
        - `kind` 'median', required
        - `field` 'duration' | 'cost' | 'tokens', required
      - object
        - `kind` 'percentile', required
        - `field` 'duration' | 'cost' | 'tokens', required
        - `p` number, required
    - `timeBucket` object — Bucket the metric over time. Omit for a single aggregate.
      - `unit` 'hour' | 'day' | 'week', required — Bucket granularity.
      - `size` integer — Number of units per bucket (e.g. `2` weeks).
    - `range` object, required — The time window.
      - `fromIso` string, date-time, required — Inclusive lower bound (ISO-8601).
      - `toIso` string, date-time, required — Exclusive upper bound (ISO-8601). Must be after `fromIso`.
    - `orderBy` object — Sort for breakdown results. Defaults to value-desc.
      - `by` 'value' | 'key'
      - `direction` 'asc' | 'desc'
    - `limit` integer — Maximum rows returned. Defaults to 50; max 500.
    - `filters` SpanRowFilterSet — Structured filter set over span row fields. `gtePercentile` is not supported — use absolute thresholds or a percentile metric.
  - object
    - `stream` 'scores', required — Scored occurrences. A signal is scores carrying a `signalId` — analyze one signal via `stream: "scores"` filtered by `score.signalId` (or broken down by `signalId`).
    - `breakdown` 'signalId' | 'source' | 'model' | 'provider' | 'service' | 'tool' | 'tag' — Dimension to group by: `signalId`/`source` (direct) or a trace dim (`model`…`tag`).
    - `metric` union, required — The metric: `count`, `passRate`, `errorRate`, or `{avg|min|max|median}` of the 0–1 score `value`.
      - object
        - `kind` 'count', required
      - object
        - `kind` 'passRate', required
      - object
        - `kind` 'errorRate', required
      - object
        - `kind` 'avg', required
        - `field` 'value', required
      - object
        - `kind` 'min', required
        - `field` 'value', required
      - object
        - `kind` 'max', required
        - `field` 'value', required
      - object
        - `kind` 'median', required
        - `field` 'value', required
    - `timeBucket` object — Bucket the metric over time. Omit for a single aggregate.
      - `unit` 'hour' | 'day' | 'week', required — Bucket granularity.
      - `size` integer — Number of units per bucket (e.g. `2` weeks).
    - `range` object, required — The time window.
      - `fromIso` string, date-time, required — Inclusive lower bound (ISO-8601).
      - `toIso` string, date-time, required — Exclusive upper bound (ISO-8601). Must be after `fromIso`.
    - `orderBy` object — Sort for breakdown results. Defaults to value-desc.
      - `by` 'value' | 'key'
      - `direction` 'asc' | 'desc'
    - `limit` integer — Maximum rows returned. Defaults to 50; max 500.
    - `filters` object — Structured filter set applied to the stream (same DSL as `listTraces`).
  - object
    - `stream` 'behaviors', required — Taxonomy observations — behavior instances clustered from session moments.
    - `breakdown` 'cluster' | 'session' | 'method' — Dimension to group by: `cluster`, `session`, or `method`.
    - `metric` union, required — The metric: `count`, or `{avg|min|max|median}` of the 0–1 assignment `confidence`.
      - object
        - `kind` 'count', required
      - object
        - `kind` 'avg', required
        - `field` 'confidence', required
      - object
        - `kind` 'min', required
        - `field` 'confidence', required
      - object
        - `kind` 'max', required
        - `field` 'confidence', required
      - object
        - `kind` 'median', required
        - `field` 'confidence', required
    - `timeBucket` object — Bucket the metric over time. Omit for a single aggregate.
      - `unit` 'hour' | 'day' | 'week', required — Bucket granularity.
      - `size` integer — Number of units per bucket (e.g. `2` weeks).
    - `range` object, required — The time window.
      - `fromIso` string, date-time, required — Inclusive lower bound (ISO-8601).
      - `toIso` string, date-time, required — Exclusive upper bound (ISO-8601). Must be after `fromIso`.
    - `orderBy` object — Sort for breakdown results. Defaults to value-desc.
      - `by` 'value' | 'key'
      - `direction` 'asc' | 'desc'
    - `limit` integer — Maximum rows returned. Defaults to 50; max 500.
    - `filters` object — Structured filter set applied to the stream (same DSL as `listTraces`).
  - object
    - `stream` 'moments', required — Semantic-moment labels — kind/actor-tagged moments detected within a session.
    - `breakdown` 'kind' | 'actor' | 'session' — Dimension to group by: `kind`, `actor`, or `session`.
    - `metric` union, required — The metric: `count`, or `{avg|min|max|median}` of the 0–1 label `confidence` or moment `coherence`.
      - object
        - `kind` 'count', required
      - object
        - `kind` 'avg', required
        - `field` 'confidence' | 'coherence', required
      - object
        - `kind` 'min', required
        - `field` 'confidence' | 'coherence', required
      - object
        - `kind` 'max', required
        - `field` 'confidence' | 'coherence', required
      - object
        - `kind` 'median', required
        - `field` 'confidence' | 'coherence', required
    - `timeBucket` object — Bucket the metric over time. Omit for a single aggregate.
      - `unit` 'hour' | 'day' | 'week', required — Bucket granularity.
      - `size` integer — Number of units per bucket (e.g. `2` weeks).
    - `range` object, required — The time window.
      - `fromIso` string, date-time, required — Inclusive lower bound (ISO-8601).
      - `toIso` string, date-time, required — Exclusive upper bound (ISO-8601). Must be after `fromIso`.
    - `orderBy` object — Sort for breakdown results. Defaults to value-desc.
      - `by` 'value' | 'key'
      - `direction` 'asc' | 'desc'
    - `limit` integer — Maximum rows returned. Defaults to 50; max 500.
    - `filters` object — Structured filter set applied to the stream (same DSL as `listTraces`).

## Response `200`

The analytics series

- AnalyticsSeries
  - `series` object[], required — Tidy series: one point per breakdown key and/or time bucket.
    - `key` string — The breakdown value, present when `breakdown` was set.
    - `label` string — Human-readable name for `key` when the breakdown value is an opaque id — the signal name for `signalId`, the cluster name for `cluster`. Absent for already-readable breakdowns.
    - `bucketStart` string — ISO-8601 start of the time bucket, present when `timeBucket` was set.
    - `value` number, required — The metric value: seconds for `duration`, dollars for `cost`, a 0–1 ratio for `errorRate`/`cacheHitRate`, otherwise a raw count/token total.

## Other responses

- `400` — Validation error
- `401` — Unauthorized
- `404` — Not found

---

[API](https://skmtc.net/latitude-dev/apis/latitude.md) · [All operations](https://skmtc.net/latitude-dev/apis/latitude/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/latitude-dev/latitude/versions/6a8789c59a5c/schema)