Usage pagination

GET /v1/usage is a forward-only cursor pagination — pass limit for the page size and use the response’s next_page token to walk forward. The cursor encodes the query fingerprint so filters cannot drift between pages.

Basic walk

# Page 1
curl 'https://api.aurous-labs.com/v1/usage?start_time=2026-04-01T00:00:00Z&end_time=2026-05-01T00:00:00Z&bucket_width=1d&group_by=type&limit=10' \
  -H "X-Api-Key: $AUROUS_API_KEY"

# Response:
# {
#   "object": "list",
#   "data": [/* 10 buckets */],
#   "has_more": true,
#   "next_page": "eyJ2IjoxLCJxZiI6IjlmYW..."
# }

# Page 2 — pass the cursor in `page_token`
curl 'https://api.aurous-labs.com/v1/usage?page_token=eyJ2IjoxLCJxZiI6IjlmYW...' \
  -H "X-Api-Key: $AUROUS_API_KEY"

When page_token is provided, you do NOT need to re-send start_time, end_time, bucket_width, group_by, or filter parameters — they’re encoded in the cursor. In fact, sending them with different values mismatches the fingerprint and returns:

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_page_token",
    "message": "page_token fingerprint mismatch — query parameters drifted between pages."
  }
}

This is intentional. A cursor that silently re-resolves params (e.g. resolves a new now for end_time on page 2) would return different data than page 1 sees — silent skew. The fingerprint check is Stripe-grade and we don’t relax it.

Cursor lifetime

Tokens expire 24 hours after the page-1 response that minted them. Walking pages slower than 24 hours apart returns 400 invalid_page_token with token_expired detail.
Tokens are scoped to your team — using a cursor from team A’s response against team B’s API key returns 400 invalid_page_token.

Cursor opacity

The next_page value is base64url-encoded JSON with version + query fingerprint + last-bucket-start + expiry. Don’t parse it yourself — treat it as opaque. Future versions of the platform may add fields or change the encoding entirely.

Known edge case — `limit` smaller than per-bucket group count

The cursor encodes last_bucket_start (the timestamp of the last bucket returned on the current page). If a bucket has N groups and your limit is less than N:

Page 1 returns the bucket with the first limit groups; has_more: true; next_page encodes that bucket’s bucket_start
Page 2 — using the cursor — starts AFTER bucket_start, so the remaining groups in that bucket are LOST

In practice this matters when:

Your group_by is multi-dimensional (e.g. group_by=type,model could produce 8 groups per bucket: 4 types × 2 models)
Your limit is unusually small (< the maximum expected groups-per-bucket)

Recommended workaround: set limit ≥ the max possible groups per bucket. For a single group_by like type (≤ 4 groups), limit ≥ 4 is safe. For multi-dim group_by, multiply: group_by=type,model → limit ≥ 16 is safe up to 8 models. The defaults (limit=100) are generous enough that most production callers never hit this. The proper fix is to paginate at the bucket level (return whole buckets, never split a bucket’s groups across pages). It’s on the v1.1 roadmap — see the pagination plan in launch-week followups.

Stable ordering

Within a response, buckets are ordered by bucket_start ascending (oldest first). Within a bucket, groups are ordered by total credit charge descending (highest spend first), then by dimensions alpha-sort tie-break. The order is stable across page walks for a given fingerprint — paging forward through a 1000-row window deterministically returns the same row order whether you do it in one shot or in five 200-row pages.

Sample code

async function fetchAllBuckets(params: Record<string, string>): Promise<unknown[]> {
  const buckets: unknown[] = [];
  let pageToken: string | undefined = undefined;
  for (;;) {
    const url = new URL("https://api.aurous-labs.com/v1/usage");
    if (pageToken) {
      url.searchParams.set("page_token", pageToken);
    } else {
      for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
    }
    const res = await fetch(url, { headers: { "X-Api-Key": process.env.AUROUS_API_KEY! } });
    const body = await res.json() as { data: unknown[]; has_more: boolean; next_page: string | null };
    buckets.push(...body.data);
    if (!body.has_more || !body.next_page) break;
    pageToken = body.next_page;
  }
  return buckets;
}

const all = await fetchAllBuckets({
  start_time: "2026-04-01T00:00:00Z",
  end_time: "2026-05-01T00:00:00Z",
  bucket_width: "1d",
  group_by: "type",
  limit: "500",
});

def fetch_all_buckets(params: dict) -> list:
    buckets = []
    next_page = None
    while True:
        query = {"page_token": next_page} if next_page else params
        res = requests.get(
            "https://api.aurous-labs.com/v1/usage",
            params=query,
            headers={"X-Api-Key": AUROUS_API_KEY},
        ).json()
        buckets.extend(res["data"])
        if not res.get("has_more") or not res.get("next_page"):
            break
        next_page = res["next_page"]
    return buckets

all_buckets = fetch_all_buckets({
    "start_time": "2026-04-01T00:00:00Z",
    "end_time": "2026-05-01T00:00:00Z",
    "bucket_width": "1d",
    "group_by": "type",
    "limit": "500",
})

Where to next?

Usage overview — the full query surface
Usage event stream — per-event detail rows
GET /v1/usage — endpoint reference

Get started

Guides

Concepts

API Reference

Resources

Basic walk

Cursor lifetime

Cursor opacity

Known edge case — `limit` smaller than per-bucket group count

Stable ordering

Sample code

Where to next?

​Basic walk

​Cursor lifetime

​Cursor opacity

​Known edge case — limit smaller than per-bucket group count

​Stable ordering

​Sample code

​Where to next?

Basic walk

Cursor lifetime

Cursor opacity

Known edge case — `limit` smaller than per-bucket group count

Stable ordering

Sample code

Where to next?