Analytics read API

A small, read-only HTTP API for the numbers in Grupr Analytics: what an organization spent on AI, grouped by department, project, model or capture source, and where each virtual key stands against its monthly cap. It exists so a script, a BI job or an agent skill can report spend without a signed-in session.

ℹ️

Everything here is GET. A read token cannot call the gateway, cannot spend, and cannot change a setting. The numbers are what Grupr recorded and priced from token counts; your provider's invoice remains the financial record.

Read tokens#

Requests are authenticated with an Analytics read token, which starts with gar_. An organization admin creates one in the web app under Analytics → API read tokens:

  • The token is shown once. Grupr stores only a hash of it.
  • It belongs to one organization. There is no organization id to pass: a request reads the token's organization and no other.
  • It can expire (30, 90 or 365 days) or have no expiry, and an admin can revoke it at any time.
  • Per-person usage is off unless the admin ticks “Include per-person usage” when creating it.
  • An organization can hold at most 20 live tokens. Creating and revoking tokens is recorded in the audit log.

Keep the token in a secret store or an environment variable. A read token is refused by every other Grupr API, and other credentials (a session, an agent token, a connector token, a virtual key) are refused here.

Making a request#

export GRUPR_ANALYTICS_TOKEN=...   # the gar_ token; never paste it anywhere else

curl -sS https://api.grupr.ai/api/v1/analytics/usage/summary \
  -H "Authorization: Bearer $GRUPR_ANALYTICS_TOKEN" \
  -H "User-Agent: spend-report/1.0"
  • Base URL: https://api.grupr.ai/api/v1/analytics
  • A User-Agent header is required; requests without one are refused at the edge.
  • Responses are wrapped as {"data": …}. Errors are {"errors":[{"code","message","field"}]}.
  • Responses carry Cache-Control: private, no-store.
  • Limit: 60 requests a minute per token. A 429 carries Retry-After and retry_after_seconds.

The time window#

since and until take an RFC 3339 time or a YYYY-MM-DD date (midnight UTC). until is exclusive. With neither, the window is the 30 days ending now. A value that does not parse is an error, not a silent default, and a window may span at most 366 days.

Endpoints#

RequestReturns
GET /The organization, the token's name and expiry, whether it may read per-person usage, the dimensions it may group by, and the maximum window
GET /usage/summaryTotals for the window and a per-model rollup
GET /usage/breakdownUsage grouped by one dimension, optionally filtered by others
GET /budgetsEach virtual key's monthly cap and month-to-date spend, and how many overage requests are pending

Usage summary#

GET /usage/summary?since=&until=

{
  "data": {
    "since": "2026-10-10T00:00:00Z",
    "until": "2026-11-09T00:00:00Z",
    "totals": { "calls": 18420, "total_tokens": 412600000, "cost_usd": 6184.37 },
    "by_model": [
      { "provider": "anthropic", "model": "claude-sonnet-5-5", "calls": 9200,
        "prompt_tokens": 201000000, "completion_tokens": 39400000,
        "total_tokens": 240400000, "cost_usd": 3961.2 }
    ]
  }
}

Usage breakdown#

GET /usage/breakdown?dimension=department&since=&until=. The default dimension is department.

{
  "data": {
    "dimension": "department",
    "since": "2026-10-10T00:00:00Z",
    "until": "2026-11-09T00:00:00Z",
    "rows": [
      { "bucket": "Engineering", "calls": 9800, "total_tokens": 231000000, "cost_usd": 3410.12 },
      { "bucket": "(unassigned)", "calls": 1520, "total_tokens": 42000000, "cost_usd": 881.5 }
    ],
    "totals": { "calls": 11320, "total_tokens": 273000000, "cost_usd": 4291.62 },
    "truncated": false
  }
}
DimensionGroups by
department, sub_departmentThe person's place in the imported directory, falling back to the labels on the virtual key
projectThe project a key is bound to or a repository maps to
functionJob title from the directory
model, providerWhat was called
tagThe type-of-work tag on the key or request
sourceWhere the usage was captured: gateway, otel (telemetry), provider_api or agent
userThe person. Needs a token created with per-person access
  • Any dimension can also be a filter: ?dimension=model&department=Engineering.
  • Usage with no value lands in a named bucket: (unassigned), (no project), (untagged), (unattributed), (unclassified).
  • At most 200 buckets are returned, largest spend first. When that limit is reached truncated is true and totals covers those 200 only; narrow with a filter to see the rest.
⚠️

Turning per-person access off blocks the user dimension and the user filter. It does not make other groupings anonymous: in a small organization a job title or a one-person team can identify someone. Decide who gets a token with that in mind.

Budgets#

GET /budgets takes no window: it is always the current calendar month, UTC.

{
  "data": {
    "month_start": "2026-11-01T00:00:00Z",
    "as_of": "2026-11-09T12:00:00Z",
    "keys": [
      { "key_id": "…", "name": "eng-shared", "department": "Engineering", "team": "Platform",
        "tag": "coding", "status": "active",
        "monthly_cap_usd": 2000, "approved_raise_usd": 0, "effective_cap_usd": 2000,
        "spend_mtd_usd": 1710.4, "remaining_usd": 289.6, "percent_used": 85.5,
        "last_used_at": "2026-11-09T11:58:00Z" }
    ],
    "totals": { "keys": 5, "capped_keys": 3, "effective_cap_usd": 2800, "spend_mtd_usd": 2496.85 },
    "pending_overage_requests": 1
  }
}
  • effective_cap_usd is the monthly cap plus any approved, unexpired overage raise. It is null for a key with no cap, as are remaining_usd and percent_used.
  • spend_mtd_usd counts gateway traffic only, the basis caps are enforced on. Usage captured from telemetry or provider reports cannot be blocked and is not counted here.
  • No key material is returned: not the key, its hash, or its display hint.

Errors#

StatusCodeWhen
401unauthorizedNo token, another kind of credential, or a token that is unknown, expired or revoked
403people_not_allowedPer-person usage requested with a token that does not allow it
400invalid_dimensionAn unknown dimension; the message lists the valid ones
400invalid_since, invalid_untilA date that does not parse
400invalid_range, range_too_largesince is not before until, or the window is over 366 days
429rate_limitedMore than 60 requests in a minute on one token

What is not in this API#

  • No writes of any kind: keys, caps, projects and approvals are managed in the web app.
  • No reconciliation against provider invoices. That view calls your providers with your admin keys, which a read token should not be able to trigger.
  • No per-request rows, prompts or responses. Totals and groupings only.
  • No roll-up across organizations: one token, one organization.
  • Spend that never reached Grupr (seat licences, tools not routed through the gateway and not reporting telemetry) is not in the numbers.

A packaged report#

The grupr-ai-spend-report skill in the public grupr-ai/skills repository calls these endpoints and prints a Markdown spend report: totals, tables by department, project and model, keys near or over their cap, and a fixed set of recommendations. It reads the token from GRUPR_ANALYTICS_TOKEN, sends it only to api.grupr.ai, and never prints it.

npx skills add grupr-ai/skills --skill grupr-ai-spend-report -a claude-code

For one agent's sandbox time and routine health, which are not money, see the agent usage report. For what Grupr Analytics does and how the caps behave, see AI spend attribution and budget controls for AI agents.

Last updated: