Insights

Insights are org-scoped saved queries and built-in Results charts. {ref} is an ins_... id, an immutable slug, or a chart reference returned by discovery. Percent-encode the reference when inserting it into a URL path.

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"

The response includes nextPageToken when another page exists.

Use experiment to discover the experiment's three built-in charts: test-results heatmap (tests), quality/efficiency scatterplot (scatter), and single-metric comparison (metric). These charts are available for existing and new experiments. Use the returned reference rather than a chart's display title.

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"

Actor and org fields always come from authentication.

GET /api/v1/insights/{ref}

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

For a built-in chart, inspect insight.chartKind, parameterSchemaJson, responseSchemaJson, and availableValuesJson. Parse each *Json field as JSON. The metadata describes parameter types, defaults, allowed values, response fields, and the experiment's available filters.

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

Retrieve chart data with the same grouping and filtering as the Results page.

curl -X POST \
  -H "Authorization: Bearer $AX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parameters":{"group_by":"model"},"result_view":"summary"}' \
  "$AX_BASE_URL/api/v1/insights/$ENCODED_INSIGHT_REF/execute?org_id=$AX_ORG_ID"

Set AX_BASE_URL to https://app.514.ax and ENCODED_INSIGHT_REF to the percent-encoded reference returned by discovery. Use your organization's id for AX_ORG_ID.

Common chart parameters:

The execution envelope contains chartDataJson, a JSON string holding the chart result. Parse it once after parsing the HTTP response:

const envelope = await response.json();
const chart = JSON.parse(envelope.chartDataJson);

Inspect responseSchemaJson for the complete field definitions. Pass rates are fractions from 0 to 1. costUsd is USD, wallSeconds is seconds, and token counts are separate from cost. Missing metric values remain null rather than zero.

For points and runs, keep the same parameters and pass the returned nextCursor as cursor until it is null. Summary statistics always cover the complete filtered population, independently of point/run pagination. A GUI display limit does not restrict programmatic retrieval.

Built-in chart definitions cannot be edited, deleted, or published through the saved-SQL insight mutation routes. Existing saved-SQL responses retain their columns/rows format.

Use chart data on your website

Call the API from your website's server and send the chart data your visitors need to the frontend. Keep the API key in your server's secret configuration. Protect your website route with your own authentication if the results are private.

This server-side TypeScript helper retrieves one fixed insight's summary. Set AX_INSIGHT_REF to a reference from discovery, and configure AX_ORG_ID, AX_API_KEY, and AX_BASE_URL on your server.

export async function loadChartSummary() {
  const { AX_BASE_URL, AX_ORG_ID, AX_API_KEY, AX_INSIGHT_REF } = process.env;
  if (!AX_BASE_URL || !AX_ORG_ID || !AX_API_KEY || !AX_INSIGHT_REF) {
    throw new Error("Configure the chart API connection on the server.");
  }

  const url = new URL(
    `/api/v1/insights/${encodeURIComponent(AX_INSIGHT_REF)}/execute`,
    AX_BASE_URL,
  );
  url.searchParams.set("org_id", AX_ORG_ID);

  const response = await fetch(url, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${AX_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      parameters: { group_by: "model" },
      result_view: "summary",
    }),
    cache: "no-store",
  });
  if (!response.ok) {
    throw new Error(`Chart request failed (${response.status}).`);
  }
  const envelope = await response.json();
  if (typeof envelope.chartDataJson !== "string") {
    throw new Error("The selected insight did not return chart data.");
  }
  return JSON.parse(envelope.chartDataJson);
}

Render the returned named metrics with your chart library. To reproduce a specific Results view, use the parameters copied from Use data, including its version, filters, and selected metric. See the CLI reference for the equivalent command.

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.

DELETE /api/v1/insights/{ref}

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