BYOK Token Usage

Overview

The Token Usage API returns raw LLM token counts aggregated by time bucket, organization, member, and model. Use it to reconcile usage against your own model provider (AWS Bedrock, Anthropic, etc.), build cost dashboards, or audit inference by user and model. This API reports tokens, not ACUs. For ACU-based billing data, use the Usage API (GET /v1/billing/usage). Availability: BYOK deployments only. Deployments that use the TextQL-managed model provider cannot access this API. Base URL: https://app.textql.com/v1/billing Endpoint: GET /v1/billing/token-usage

Authentication

Same as the Usage API. All requests require an API key with billing:read permission. Create keys in Settings → Developers → API Keys. The token is Base64-encoded {member_id}:{api_token}. Pass it in one of two ways:

# Authorization header
-H 'Authorization: Bearer YOUR_TOKEN'

# Or as a custom header
-H 'tql_api_key: YOUR_TOKEN'

The API key’s organization determines tenant scope: results include all organizations in that tenant (unless filtered by organization).

Your First Request

Fetch the last 90 days of token usage for your tenant:

curl 'https://app.textql.com/v1/billing/token-usage' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Example response:

{
  "data": [
    {
      "start_datetime": "2026-01-31T00:00:00Z",
      "end_datetime": "2026-02-01T00:00:00Z",
      "organization": "acme-engineering",
      "email": "m.chen@acme.com",
      "model": "claude-sonnet-4-6",
      "input_tokens": 125000,
      "cache_read_input_tokens": 45000,
      "cache_write_input_tokens": 12000,
      "output_tokens": 38000,
      "total_tokens": 220000,
      "request_count": 142
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 100,
    "total_count": 1
  }
}

Each record is one (time bucket × organization × member × model) slice. Token fields are summed across all LLM requests in that slice.

Query Parameters

All parameters are optional query parameters on GET /token-usage. Unrecognized query parameters are rejected with 400 invalid_parameter — in particular, the response fields start_datetime / end_datetime are not valid request filters; use start_date / end_date.

Date range

Parameter	Format	Default	Description
`start_date`	RFC 3339	90 days before `end_date`	Inclusive lower bound
`end_date`	RFC 3339	Current UTC time	Exclusive upper bound

Timezones are expressed through the RFC 3339 UTC offset (e.g. 2026-07-04T20:00:00-04:00). The offset of start_date (or of end_date when start_date is omitted) also controls:

Alignment of day and month buckets (days start at local midnight for that offset)
The offset used to render start_datetime / end_datetime in the response

Constraints:

start_date must be before end_date.
The window end_date − start_date cannot exceed 90 days.
Remember to URL-encode + in positive offsets as %2B (e.g. 2026-07-01T00:00:00%2B05:30).

curl 'https://app.textql.com/v1/billing/token-usage?start_date=2026-01-01T00:00:00Z&end_date=2026-02-01T00:00:00Z' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Granularity

Controls time bucket size. Default: day.

Value	Bucket size	`end_datetime` offset
`hour`	1 hour	`start_datetime + 1 hour`
`day`	1 calendar day (at the request’s UTC offset)	`start_datetime + 1 day`
`month`	1 calendar month (at the request’s UTC offset)	`start_datetime + 1 month`

curl 'https://app.textql.com/v1/billing/token-usage?granularity=hour&start_date=2026-06-10T00:00:00Z&end_date=2026-06-11T00:00:00Z' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Filtering

By organization — comma-separated organization names (not UUIDs). Omit to include all organizations in the tenant.

curl 'https://app.textql.com/v1/billing/token-usage?organization=acme-engineering,acme-research' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Unknown organization names return 400 invalid_parameter. By user email — comma-separated, case-insensitive. Only members whose email matches (in the selected orgs) are included. If no members match, the response is an empty data array with 200 OK.

curl 'https://app.textql.com/v1/billing/token-usage?email=j.ramirez@acme.com,s.patel@acme.com' \
  -H 'Authorization: Bearer YOUR_TOKEN'

By model — comma-separated model names as stored in usage records (e.g. claude-sonnet-4-6, gpt-4o). Exact match.

curl 'https://app.textql.com/v1/billing/token-usage?model=claude-sonnet-4-6,gpt-4o' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Filters can be combined:

curl 'https://app.textql.com/v1/billing/token-usage?organization=acme-engineering&email=m.chen@acme.com&model=claude-sonnet-4-6&granularity=day&start_date=2026-01-27T00:00:00Z&end_date=2026-02-03T00:00:00Z' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Sorting

Use sort to order results before pagination. Prefix with - for descending. Default: -start_datetime (newest buckets first).

Value	Description
`start_datetime`	Oldest bucket first
`-start_datetime`	Newest bucket first (default)
`email`	Alphabetical by user email
`-email`	Reverse alphabetical by email
`model`	Alphabetical by model name
`-model`	Reverse alphabetical by model
`total_tokens`	Lowest total tokens first
`-total_tokens`	Highest total tokens first

Tie-break order (when primary sort values match): email → model → start_datetime → organization → total_tokens.

curl 'https://app.textql.com/v1/billing/token-usage?sort=-total_tokens' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Pagination

Parameter	Default	Max
`page_size`	100	1000
`page`	1	—

curl 'https://app.textql.com/v1/billing/token-usage?page=2&page_size=50' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Use pagination.total_count to compute total pages. Requesting a page beyond the last page returns an empty data array with the requested page and correct total_count.

Response Fields

Top level

Field	Type	Description
`data`	array	Token usage records (see below)
`pagination.page`	integer	Current page (1-based)
`pagination.page_size`	integer	Page size used for this response
`pagination.total_count`	integer	Total matching records across all pages

Record object (`data[]`)

Field	Type	Description
`start_datetime`	string (RFC 3339, at the request’s UTC offset)	Start of the time bucket, inclusive
`end_datetime`	string (RFC 3339, at the request’s UTC offset)	End of the time bucket, exclusive
`organization`	string	Organization name
`email`	string	Member email, lowercase. Empty string if usage is non-attributed (see below)
`model`	string	Model name
`input_tokens`	integer	Sum of input/prompt tokens
`cache_read_input_tokens`	integer	Sum of cache-read input tokens
`cache_write_input_tokens`	integer	Sum of cache-write input tokens
`output_tokens`	integer	Sum of output/completion tokens
`total_tokens`	integer	Sum of all four token fields above
`request_count`	integer	Number of LLM usage events in this bucket

total_tokens calculation:

total_tokens = input_tokens + cache_read_input_tokens + cache_write_input_tokens + output_tokens

Member Attribution

Usage is attributed to a member when member_id is present on the underlying usage event and the member’s email is not a TextQL staff domain. Non-attributed usage (empty email):

Usage with no member attribution
Usage from @textql.com or *.textql.com email addresses (TextQL staff)

Non-attributed rows are still returned with "email": "". Clients may display these as “(non-attributed)” in UI.

BYOK Requirement

This API is only available when your deployment uses your own model provider (BYOK — bring your own keys).

Deployment type	Token Usage API
BYOK (customer-managed provider)	Available
TextQL-managed provider	Not available — `403 forbidden`

Error when not BYOK:

{
  "code": "forbidden",
  "message": "token usage API is only available for BYOK deployments"
}

Comparison with Usage API

	Usage API	Token Usage API
Path	`GET /v1/billing/usage`	`GET /v1/billing/token-usage`
Metric	ACU	Raw token counts
Grouping	category (`llm_tokens`, `compute_hours`, …)	model name
BYOK required	No	Yes
Extra fields	`category`, `acu`, `cost_center`	`model`, `input_tokens`, `cache_*`, `output_tokens`, `total_tokens`, `request_count`
Sort options	includes `acu` / `-acu`	includes `total_tokens`, `model`

Shared behavior: auth, tenant scoping, organization / email filters, date range defaults, 90-day max window, granularity, pagination.

Code Examples

Python — paginate all token usage for January

import requests

TOKEN = "your-token"
BASE = "https://app.textql.com/v1/billing"
headers = {"Authorization": f"Bearer {TOKEN}"}

def get_all_token_usage(**params):
    records = []
    page = 1
    while True:
        resp = requests.get(
            f"{BASE}/token-usage",
            headers=headers,
            params={**params, "page": page, "page_size": 1000},
        )
        resp.raise_for_status()
        data = resp.json()
        records.extend(data["data"])
        if len(records) >= data["pagination"]["total_count"]:
            break
        page += 1
    return records

usage = get_all_token_usage(
    start_date="2026-01-01T00:00:00Z",
    end_date="2026-02-01T00:00:00Z",
    granularity="day",
)

JavaScript — top models by token volume (last 90 days)

const TOKEN = "your-token";
const BASE = "https://app.textql.com/v1/billing";

async function getTokenUsage(params = {}) {
  const query = new URLSearchParams(params).toString();
  const res = await fetch(`${BASE}/token-usage?${query}`, {
    headers: { Authorization: `Bearer ${TOKEN}` },
  });
  if (!res.ok) throw new Error(await res.text());
  return res.json();
}

const data = await getTokenUsage({
  granularity: "month",
  sort: "-total_tokens",
  page_size: 20,
});

Error Reference

Errors use the same envelope as the Usage API:

{
  "code": "error_code",
  "message": "Human-readable description"
}

HTTP status	`code`	Typical cause
400	`invalid_parameter`	Invalid date format; `start_date` ≥ `end_date`; date range > 90 days; invalid `granularity` or `sort`; invalid email format; unknown `organization` name; invalid `page` / `page_size`; unrecognized query parameter (e.g. `start_datetime` instead of `start_date`)
403	`forbidden`	Missing/invalid/expired API key; insufficient permissions; or deployment is not BYOK
500	`internal_error`	Server-side failure retrieving usage

Note: Authentication failures return 403 (not 401) with code: "forbidden".

Troubleshooting & Support

Problem	What to check
403 `token usage API is only available for BYOK deployments`	Deployment must use customer-managed model keys, not TextQL-managed provider
403 on every request	Token format (`{member_id}:{api_token}` Base64), expiry, and `billing:read` permission
Empty `data`	Widen date range; remove `email` / `model` filters; confirm LLM usage exists for the tenant
Unknown organization	`organization` must be the exact org name as shown in TextQL, not a UUID
`email` is empty on some rows	Expected for non-attributed usage (unattributed events or TextQL staff)
Counts differ from provider bills	This API reflects TextQL-recorded usage; provider billing may use different bucketing or attribution

If you’re still running into issues, contact support at support@textql.com and include the full request URL and response body.

Get Started

How It Works

Set Up Your Data

Integrations

Ontology

Get Better Results

Admin & Security

FAQ

Legacy Features

Overview

Authentication

Your First Request

Query Parameters

Date range

Granularity

Filtering

Sorting

Response Fields

Top level

Record object (`data[]`)

Member Attribution

BYOK Requirement

Comparison with Usage API

Code Examples

Python — paginate all token usage for January

JavaScript — top models by token volume (last 90 days)

Error Reference

Troubleshooting & Support

​Overview

​Authentication

​Your First Request

​Query Parameters

​Date range

​Granularity

​Filtering

​Sorting

​Pagination

​Response Fields

​Top level

​Record object (data[])

​Member Attribution

​BYOK Requirement

​Comparison with Usage API

​Code Examples

​Python — paginate all token usage for January

​JavaScript — top models by token volume (last 90 days)

​Error Reference

​Troubleshooting & Support

Overview

Authentication

Your First Request

Query Parameters

Date range

Granularity

Filtering

Sorting

Pagination

Response Fields

Top level

Record object (`data[]`)

Member Attribution

BYOK Requirement

Comparison with Usage API

Code Examples

Python — paginate all token usage for January

JavaScript — top models by token volume (last 90 days)

Error Reference

Troubleshooting & Support