# 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 recent operational telemetry, not authoritative workflow state.
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.

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