Overview
One endpoint, two shapes. Call GET /report with no parameters for a same-day snapshot — revenue today vs. yesterday, plus month-to-date spend and profit — or add start/end for a custom time series. Both return JSON, scoped to the four exchanges Insights Agent already ingests.
This API is separate from the Insights Agent chat UI. It shares no session, cookie, or Google sign-in with it — access is entirely by bearer token, described below.
Authentication
Every route except /health requires a bearer token:
Authorization: Bearer ira_<token_id>.<secret>
There's no self-serve signup form. Tokens are issued, listed, and revoked entirely from inside the Insights Agent chat — the same Google-account-gated tool that already has an audit trail, rather than a second admin surface to secure separately.
Generating a token
Open Insights Agent chat and ask in plain language:
Generate a token to the insights reporting API, valid for 30 days
Give it a lifetime in days, or say unlimited for a token that never expires until you revoke it. Add a label — e.g. "...label it '140Proof dashboard'" — to make it easy to identify later.
The raw token appears exactly once, in the response:
{
"token": "ira_58b23fecaf13.E2goZDFDWQys99Qhx7Omd7jMzpPkfYrdeAnKf-ETgI8",
"token_id": "58b23fecaf13",
"label": "140Proof dashboard",
"expires_at": "2026-10-04T18:00:00+00:00",
"warning": "This token is shown ONLY ONCE and cannot be retrieved again..."
}
Copy it immediately — only its hash is ever stored server-side. A lost token can't be recovered, only revoked and replaced.
Listing & revoking
"List my reporting API tokens" shows every token — label, creator, dates, revoked/last-used status — never the raw secret. "Revoke token 58b23fecaf13" invalidates it immediately and permanently.
Default report
No query parameters — today's snapshot, per exchange, plus a combined total.
| Field | Meaning |
|---|---|
revenue_today / _yesterday | What demand partners spent through BKO that day. |
pct_change | Day-over-day % change. null if yesterday was zero. |
mtd_spend | Same metric as revenue — summed month-to-date, not a different figure. |
mtd_profit | MTD spend minus MTD supply payout — BKO's actual margin. |
All figures exclude BKO's own cross-platform internal trading and use UTC day/month boundaries.
What it looks like
Custom range
Add start and end for a flat time series instead — no "vs. yesterday" or MTD framing, since neither generalizes to an arbitrary window.
| Parameter | Required | Description |
|---|---|---|
start | with end | ISO 8601 timestamp, inclusive. |
end | with start | ISO 8601 timestamp, exclusive. |
group_by | no — default day | hour, day, or month. |
start and end must arrive together — one without the other is a 400, never a silent fallback to the default view.
(Truncated — a real call returns one row per platform per bucket across the full range, ordered by source, then period.)
Request builder
Build the exact call for your integration. Swap in your own token before running it.
Errors
Every error returns {"detail": "..."}.
| Status | Cause | Detail |
|---|---|---|
| 401 | No Authorization header | missing Authorization: Bearer <token> header |
| 401 | Malformed token | malformed token |
| 401 | Token doesn't exist | unknown token |
| 401 | Token was revoked | token has been revoked |
| 401 | Lifetime expired | token has expired |
| 401 | Secret doesn't match | invalid token |
| 400 | Only one of start/end given | start and end must both be provided together... |
| 400 | Bad group_by | group_by must be one of ('hour','day','month')... |
Notes
- No rate limiting is enforced today — be a reasonable caller regardless; this queries a 150M+-row warehouse table on every call.
- Tokens are global in scope — any valid token sees all four platforms. There's no per-partner data scoping yet.
- Revocation is immediate — no grace period.
GET /healthneeds no token and touches no data — use it for uptime checks.