Documentation / Analytics / Operate

Query and export analytics

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

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

  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
  }'
  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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

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

Use Create and publish Datasets for trace capture, Instrument custom analytics for application events, Run operations for exact execution evidence, and Operate Policies for authorization investigations.