# Query analytics with the CLI

> Retrieve summaries, live telemetry, dashboards, historical aggregates, raw events, and immutable exports.

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

Obtain `analytics:read` and, for durable exports, `analytics:export`. Select the namespace and define the narrowest time window, supported grouping, and filters that answer the operational question. Use Run workflow state when you need an authoritative current answer.

## Steps {#steps}

1. Read the recent summary with `constal analytics summary --output json`.
2. Query hot telemetry with `analytics live` or the Console-shaped `analytics dashboard`, supplying reviewed JSON through `--body @query.json`.
3. Run a historical aggregate or bounded raw query:

   ```sh
   constal analytics query --body @historical-query.json --output json
   ```

4. Check the returned window, grouping, filters, generation time, and `truncated` flag. Narrow the query rather than assuming the limit is a pagination cursor.
5. Create an immutable result with `analytics export --body @historical-query.json`, retain its content-addressed reference, and download it with `analytics export-get <ref> --out report.json`.

## Verify {#verify}

Compare incident-critical aggregates with exact Run journals or workflow state. Confirm custom event id/version and bounded dimensions match the SDK declaration. Ensure exported files contain only the authorized namespace and redacted detail level.

## Next steps {#next-steps}

Read [Instrument analytics with the SDK](/docs/analytics/sdk.md), [Query and export analytics](/docs/analytics/query-and-export.md), and the generated [Analytics command reference](/docs/cli/reference.md#analytics).