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

Query a historical aggregate:

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
  }'

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

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 Instrument custom analytics for application events, Run operations for exact execution evidence, and Operate Policies for authorization investigations.