# Query and export analytics

> Retrieve recent or historical metrics with bounded windows, filters, grouping, raw detail, and immutable export artifacts.

## Before you begin {#before-you-begin}

Obtain `analytics:read` for queries and `analytics:export` for exports. Choose the narrowest time window and decide whether you need an aggregate or individual raw events. Use the live workflow endpoint instead when the question is “what is this Run doing right now?”

## Steps {#steps}

1. Query a historical aggregate:

   ```sh
   curl https://platform.constal.ai/v1/namespaces/default/analytics/query \
     -H "Authorization: Bearer $CONSTAL_API_KEY" \
     -H "Content-Type: application/json" \
     --data '{
       "start":"2026-08-21T00:00:00Z",
       "end":"2026-08-22T00:00:00Z",
       "interval":"hour",
       "group_by":["agent_id","outcome"],
       "filters":{"event_type":"workflow"},
       "limit":500
     }'
   ```

2. Use `interval` values `minute`, `hour`, or `day`; use at most four supported `group_by` dimensions. Query windows can span at most three years and limits range from 1 to 1,000.
3. Set `raw: true` for bounded individual events. Raw queries cannot also use interval or grouping. Set `include_detail: true` only when authorized investigation requires redacted ledger, journal, state, or audit detail.
4. Use `POST .../analytics/live` or `/dashboard` for recent hot data up to thirty days. Treat this projection as approximate operational telemetry. It may contain at-least-once duplicates or omit best-effort request points; use the historical query surface for exact deduplicated event totals.
5. Create a durable result with `POST .../analytics/exports` using the same query shape. Store the returned content-addressed `ref`, then download `GET .../analytics/exports/:ref`. Narrow the query if the artifact would exceed 10 MiB.
6. To build an Eval Dataset from selected Runs, export raw workflow events with exact time and Agent/outcome filters, review the export, then pass its `ref` to the Dataset capture route. The Evals workflow resolves exact Run identity and lineage from the artifact; it does not copy raw traces into a model prompt.

## Verify {#verify}

Check the response’s `start`, `end`, grouping, filters, `generated_at`, and `truncated` flag. If truncated, narrow the window or filters; do not assume a limit is pagination. Compare incident-critical results with the exact Run journal or workflow owner.

## Next steps {#next-steps}

Use [Create and publish Datasets](/docs/evals/datasets.md) for trace capture, [Instrument custom analytics](/docs/analytics/instrument.md) for application events, [Run operations](/docs/runs/operate.md) for exact execution evidence, and [Operate Policies](/docs/policies/operate.md) for authorization investigations.