Get usage bucketed and grouped

Part of Usage & spend, 8 operations. The overview covers keys, scopes and errors.

GET /v1/usage/breakdown

Usage bucketed by hour or day, grouped by key, lane, role, session or model, narrowed by any filter. A person key reads its own person’s usage here, never the account’s.

A caller key holding usage:read (Authorization: Bearer sbc_… or x-api-key: sbc_…), or a signed-in session.

Operation id getUsageBreakdown in Usage & spend.

Query parameters

from string (date) optional
YYYY-MM-DD; default 30 days before to.
to string (date) optional
YYYY-MM-DD; default today (UTC).
tz string optional
IANA zone the days and buckets are read in; default UTC.
bucket string optional
Bucket width; default day. One of day, hour.
group string optional
Split dimension; default none. One of none, key, lane, role, session, model.
key string optional
Only rows from this key id.
lane string optional
Only rows on this lane.
role string optional
Only rows with this agent role.
session string optional
Only rows in this session.

Response 200

Buckets, groups and totals.

application/json: UsageBreakdown.

from string required
to string required
tz string required
bucket string required
One of day, hour.
group string required
totals UsageMetrics required
8 fields
- requests integer required
- tokens_in number required
- tokens_out number required
- cache_read number required
- cache_write number required
- tokens number required
  Billed credits.
- usd number required
- list_usd number required
groups array of UsageMetrics & object required
10 fields
- requests integer required
- tokens_in number required
- tokens_out number required
- cache_read number required
- cache_write number required
- tokens number required
  Billed credits.
- usd number required
- list_usd number required
- id string required
- label string required
buckets array of UsageMetrics & object required
11 fields
- requests integer required
- tokens_in number required
- tokens_out number required
- cache_read number required
- cache_write number required
- tokens number required
  Billed credits.
- usd number required
- list_usd number required
- key string required
- start string required
- by object required

Errors

Status	Code	What to change
400	`invalid_request`	A parameter or body field is invalid; `param` names it and `issues` lists every problem.
401	`unauthorized`	Send a live caller key or session as `Authorization: Bearer …` or `x-api-key`. No key yet: create one at /account/api, or sign a user in at /auth.md.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.

view .md openapi

Request

curl

curl -sS -X GET "https://superbot.gg/v1/usage/breakdown" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY"

JavaScript

const res = await fetch(`https://superbot.gg/v1/usage/breakdown`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os
import requests

res = requests.request(
    "GET",
    "https://superbot.gg/v1/usage/breakdown",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())

Response

200 Buckets, groups and totals.

{
  "from": "your-from",
  "to": "your-to",
  "tz": "your-tz",
  "bucket": "day",
  "group": "your-group",
  "totals": {
    "requests": 0,
    "tokens_in": 0,
    "tokens_out": 0,
    "cache_read": 0,
    "cache_write": 0,
    "tokens": 0,
    "usd": 0,
    "list_usd": 0
  },
  "groups": [
    {
      "requests": 0,
      "tokens_in": 0,
      "tokens_out": 0,
      "cache_read": 0,
      "cache_write": 0,
      "tokens": 0,
      "usd": 0,
      "list_usd": 0,
      "id": "your-id",
      "label": "your-label"
    }
  ],
  "buckets": [
    {
      "requests": 0,
      "tokens_in": 0,
      "tokens_out": 0,
      "cache_read": 0,
      "cache_write": 0,
      "tokens": 0,
      "usd": 0,
      "list_usd": 0,
      "key": "your-key",
      "start": "your-start",
      "by": {}
    }
  ]
}

400 The request is malformed or a parameter is invalid; `param` names the field.

{
  "error": "invalid_request",
  "message": "A parameter or body field is invalid; param names it and issues lists every problem.",
  "doc_url": "https://superbot.gg/developers#errors-invalid_request",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

401 The bearer is missing, malformed or unknown.

{
  "error": "unauthorized",
  "message": "Send a live caller key or session as Authorization: Bearer … or x-api-key. No key yet: create one at /account/api, or sign a user in at /auth.md.",
  "doc_url": "https://superbot.gg/developers#errors-unauthorized",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

403 The key lacks a scope (insufficient_scope), is revoked, or may not call this route.

{
  "error": "insufficient_scope",
  "message": "The key lacks the scope in required_scopes; mint a key that holds it.",
  "doc_url": "https://superbot.gg/developers#errors-insufficient_scope",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}