Build custom reports

When the App dashboard doesn't have the metric your team cares about, the analytics API hands back the same pre-aggregated rollups the dashboard is built on. Wire them into your existing BI tool, ops alerting, or weekly report.

What the analytics API exposes

• Yearly summaries — top-line totals for long-range trends. The right shape for executive year-over-year comparisons.
• Daily summaries — daily rollups of cache hits, misses, and warehouse-bound volume. The right shape for week/month dashboards and threshold-based alerting.
• Per-user summaries — usage and outcomes broken out by warehouse user. The right shape for chargeback reports, abuse detection, and capacity planning.

Every endpoint returns JSON in a shape designed to load into a BI tool without further reshaping. See the analytics API reference for fields, types, and pagination.

Authenticate with a personal access token

Custom-report pipelines don't run in the App, so they need a non-interactive credential. Mint a personal access token in the App's API explorer and scope it to read-only access on the analytics endpoints. See Create a personal access token and Scope a token for the steps.

Token scope, in plain language for this use case:

• Method: GET only.
• Path: the analytics endpoints you'll call.
• Tenant: a single tenant (or all your tenants, if your report spans them).
• Account: the account whose tenants you're reporting on.

Pull a daily summary

A minimal end-to-end pull, using curl:

curl -H "Authorization: Bearer $AIRBRX_PAT" \
  "https://api.airbrx.ai/tenants/<tenant-id>/summaries/2026/04/15"

The response carries that day's cache outcome counts, the byte totals behind the App's savings tile, an hourlyActivity breakdown, and a queries array with one entry per distinct statement. Summaries are addressed by date rather than by a range, so a month is a loop over /{year}/{month}/{day} — or a single call to /{year}/{month} if the month's totals are all you need.

Load into a BI tool

The analytics endpoints return small payloads compared to warehouse extracts — a year of daily data fits comfortably in memory. Two practical patterns:

• Direct pull. Most BI tools (Power BI, Tableau, Excel) can consume JSON from an authenticated REST endpoint. Configure the source with the PAT as a bearer token and a refresh schedule that suits your cadence.
• Land in warehouse first. Pull on a cron job, write to a table in your existing warehouse, and report against the table. This is the right pattern if you want to join Airbrx traffic data against warehouse-side context (cost units, departments, datasets).

Alerting examples

• Hit-rate floor. Page if the daily hit rate drops below a tenant-specific threshold for two consecutive days. Catches rule drift faster than the human eye on the dashboard.
• Spend ceiling. Page if estimated weekly savings drops by more than a fixed amount week-over-week. Often the first signal that a BI tool stopped routing through the Gateway.
• Per-user volume spike. Notify when a single user runs more than N statements in an hour. Catches runaway scripts before they pile up warehouse spend.

What's not on the analytics API

The summary endpoints are aggregates, by design — day, month, year, user. A report that needs one row per execution, or a GROUP BY nobody anticipated, wants the log itself rather than a rollup of it.

That is a different endpoint, not a dead end: POST /tenants/{tenant}/query runs read-only SQL against every statement that crossed the Gateway. See Query the raw log for the workflow, and the query log reference for the record and its storage layout.

One caution when you mix the two in the same report: on the summary endpoints, a field named cacheMisses counts every non-hit — MISS, BYPASS and PASSTHROUGH together. In SQL you can filter on the exact cache status, so the two will disagree unless you ask them the same question.

Where to go next

• Analytics API reference — endpoint shapes and parameters.
• Query the raw log — SQL over per-statement data, when a rollup won't do.
• Scope a token — least-privilege scoping for a pipeline PAT.
• Read the dashboard — the metrics the analytics API is built from.