ax insight
Discover, inspect, and execute saved SQL and Results chart insights.
Insights are saved SQL queries with a heading and an immutable slug. Create
them here, or from a query with --save on
experiment query /
run query. Listing never re-executes SQL; view and
export re-execute live against your org's uploaded results data. Every experiment
also has built-in test-results heatmap, quality/efficiency scatterplot, and
single-metric comparison insights.
| Command | Use |
|---|---|
insight list | List insights (metadata only). |
insight view | Execute an insight or inspect its query and schemas. |
insight create | Create an insight from a heading and SQL. |
insight share | Publish a public capability URL for one insight. |
insight edit | Update heading, description, labels, or SQL. |
insight delete | Delete one insight. |
insight export | Write an insight's live result to a file. |
All commands accept --org <org-id>; list and view also accept --json.
Arguments marked required must be supplied; everything else is optional.
insight list
List insights: slug, heading, owner, labels, updated. No SQL runs.
ax insight list| Argument / flag | What it does |
|---|---|
--search <text> | Case-insensitive search over slug, heading, description, owner. |
--owner <user-id> | Filter by the original owner. |
--experiment <id> / --run <id> | Filter by provenance. An experiment also includes its three built-in chart insights. |
--label <label> | Require this label. |
--limit <n> | Max insights (default 50). |
insight view
Execute an insight live, or inspect its saved query and chart schemas.
ax insight view <SLUG | ID>| Argument / flag | What it does |
|---|---|
<SLUG | ID> | Required. Saved insight slug/id or chart reference from insight list. |
--sql | Print only the stored query without executing; incompatible with --json. |
--sql-only | Inspect metadata, query, parameter schema, response schema, and available filter values; accepts --json. |
--parameters <JSON> | Chart parameters as a JSON object; defaults and allowed values are in the parameter schema. |
--result-view <VIEW> | summary (default), points, or runs. Available views depend on the chart. |
--group-value <VALUE> / --test-name <NAME> | Exact group and test for underlying runs; heatmap cell runs require both. |
--cursor <CURSOR> | Continue a points or runs page using nextCursor. Keep the same parameters and view. |
--json | Return the execution envelope; chart results are in chart_data, SQL results in rows. |
--limit <N> | Maximum SQL rows (default 100, max 1000). Omit for chart insights. |
Chart inspection returns chart_kind, parameter_schema, response_schema,
and available_values. Inspect before choosing experiment-specific versions,
models, products, or other filters. All chart parameters are optional. Use
group_by to choose variant, model, agent, agent_mode, prompt,
environment, or product; empty filter lists mean no filter.
Chart summaries cover all matching runs. For points and underlying runs, pass
chart_data.nextCursor to the next call until it is null. Pagination does not
change the summary statistics. Human-readable metric comparisons put highest
pass-rate means first and lowest means first for other metrics; ties use the
group value. JSON preserves the API's ordering and missing-value semantics.
Examples:
# Discover and inspect an experiment's chart insights
ax insight list --experiment <EXPERIMENT_ID> --json
ax insight view '<INSIGHT_REF>' --sql-only --json
# Compare wall time by model
ax insight view '<METRIC_INSIGHT_REF>' --parameters '{"group_by":"model","metric":"wallSeconds"}' --json
# Retrieve a page of scatter points, then continue with its nextCursor
ax insight view '<SCATTER_INSIGHT_REF>' --parameters '{"group_by":"agent"}' --result-view points --json
ax insight view '<SCATTER_INSIGHT_REF>' --parameters '{"group_by":"agent"}' --result-view points --cursor '<NEXT_CURSOR>' --json
# Inspect runs for an exact heatmap cell
ax insight view '<TESTS_INSIGHT_REF>' --parameters '{"group_by":"product"}' --result-view runs --group-value '<PRODUCT>' --test-name '<TEST_NAME>' --jsonUse the insights API to retrieve the same data from your website's server. MCP insight tools provide the same discovery, inspection, and execution to agents.
insight create
Create an insight from a heading and SQL. The slug is minted from the heading and is immutable afterwards.
ax insight create "<HEADING>" --sql '<SQL>'| Argument / flag | What it does |
|---|---|
<HEADING> | Required. Human heading; also mints the slug unless --slug is given. |
--sql <SQL|@file|-> | Required. Inline SQL, @file.sql, or - for stdin. |
--slug <slug> | Explicit slug (kebab-case). A collision errors unless --force. |
--description <text> | Optional description. |
--label <label> | Labels to attach (repeatable). |
--force | Overwrite mutable content when the slug already exists. |
Example:
ax insight create "Cross-experiment cost" --sql @cost.sql --label finance
ax insight view cross-experiment-costinsight share
Print a stable public capability URL for one insight. The first share freezes the heading, description, query, analytical data family, and execution scope; later edits to the source insight do not change that snapshot. The public page still reruns the frozen query against live data, so rows can change. Repeated shares return the same URL. Deleting the source insight revokes the share.
ax insight share <SLUG | ID>| Argument / flag | What it does |
|---|---|
<SLUG | ID> | Required. Insight slug or ins_... id. |
insight edit
Update an insight's mutable fields. The slug never changes.
ax insight edit <SLUG | ID>| Argument / flag | What it does |
|---|---|
<SLUG | ID> | Required. Insight slug or ins_... id. |
--heading <text> | New heading. |
--description <text> | New description; pass an empty string to clear. |
--label <label> | Replace the label set (repeatable); --clear-labels clears it. |
--sql <SQL|@file|-> | New SQL. |
insight delete
Delete one insight by slug or id. No confirmation prompt.
ax insight delete <SLUG | ID>insight export
Re-execute a saved SQL insight once and write the result to a file. For chart data, redirect ax insight view <REF> --json to a file.
ax insight export <SLUG | ID> <PATH>| Argument / flag | What it does |
|---|---|
<SLUG | ID> | Required. Insight slug or ins_... id. |
<PATH> | Required. Destination file; overwritten if it exists. |
--format <fmt> | csv, json, tsv, or md. Inferred from the extension when omitted. |
--limit <n> | Max SQL rows (default 100, max 1000). |