Insights | AX Documentation

Insights are org-scoped saved SQL queries. {ref} is an ins_... id or the immutable slug.

Route	Use	CLI equivalent
`GET /insights`	List insight metadata.	`ax insight list`
`POST /insights`	Create an insight.	`ax insight create`
`GET /insights/{ref}`	Execute or inspect one insight.	`ax insight view`
`POST /insights/{ref}/share`	Publish an immutable public insight URL.	`ax insight share`
`PATCH /insights/{ref}`	Update mutable fields.	`ax insight edit`
`DELETE /insights/{ref}`	Delete an insight.	`ax insight delete`

Every route takes org_id (required only when the key can see several orgs). Parameters are optional unless marked required. Insight export stays client-side over the live GET response; there is no server export route.

`GET /api/v1/insights`

List insight metadata; no SQL runs.

curl -H "Authorization: Bearer $AX_API_KEY" \
  "https://app.514.ax/api/v1/insights?search=cost&limit=20"

Parameter	What it does
`search`	Text search over slug, heading, description, owner (`query` is an alias).
`owner`	Original owner's user id (`owner_user_id` is an alias).
`experiment` / `run`	Provenance filters (`experiment_id` / `run_id` are aliases).
`label`	Require this label.
`limit` / `page_token`	Pagination (`page_size` is an alias for `limit`).

The response includes nextPageToken when another page exists.

`POST /api/v1/insights`

Create an insight.

curl -X POST \
  -H "Authorization: Bearer $AX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"heading":"Cross-experiment cost","sql":"SELECT ..."}' \
  "https://app.514.ax/api/v1/insights"

Body field	What it does
`heading`	Required. Human heading; mints the slug unless `slug` is given.
`sql`	Required. The SQL body.
`slug`	Explicit slug (immutable after create).
`description` / `labels`	Optional metadata.
`force`	Overwrite mutable content when the slug already exists.
`provenance`	`{kind, experimentId, runId}` where `kind` is `none`, `experiment`, or `run`.
`dataSchema`	`legacy` or `session_data_v1`. Omitted defaults new insights to legacy and preserves the stamp on force overwrite.

Actor and org fields always come from authentication.

`GET /api/v1/insights/{ref}`

Execute the stored SQL live (the default, like ax insight view).

Parameter	What it does
`sql_only`	`true` returns stored metadata and SQL without executing (`sqlOnly` is an alias).
`limit`	Max live rows, up to 1,000.

`POST /api/v1/insights/{ref}/share`

Create or reuse an insight's immutable public publication. The response is {"url":"https://.../embed/insights/<token>"}. The URL is public: anyone who has it can see the publication's live query result. The query definition and presentation metadata are frozen on first share, while underlying data remains live. Source edits do not refresh the publication, and repeated requests return the same URL. Deleting the source insight is the only revocation mechanism in this release.

`PATCH /api/v1/insights/{ref}`

Partially update mutable fields. Ids and slugs are immutable.

Body field	What it does
`heading`	New heading.
`sql`	New SQL.
`description`	New description; an empty string clears it.
`labels`	Replace the label set; an empty array or `clear_labels: true` clears it (not both).

`DELETE /api/v1/insights/{ref}`

Delete an insight. Deleting a missing reference is idempotent and returns deleted: false.

Search documentation

GET /api/v1/insights

POST /api/v1/insights

GET /api/v1/insights/{ref}

POST /api/v1/insights/{ref}/share

PATCH /api/v1/insights/{ref}