Usage API

# Authorization header
-H 'Authorization: Bearer YOUR_TOKEN'

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

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

{
  "data": [
    {
      "start_datetime": "2026-01-31T00:00:00Z",
      "end_datetime": "2026-02-01T00:00:00Z",
      "organization": "acme-engineering",
      "email": "m.chen@acme.com",
      "category": "llm_tokens",
      "acu": 8241.05
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 100,
    "total_count": 3
  }
}

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

# Monthly rollup
curl 'https://app.textql.com/v1/billing/usage?granularity=month' \
  -H 'Authorization: Bearer YOUR_TOKEN'

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

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

curl 'https://app.textql.com/v1/billing/usage?category=llm_tokens,compute_hours' \
  -H 'Authorization: Bearer YOUR_TOKEN'

# LLM usage for one user, by hour, for a specific week
curl 'https://app.textql.com/v1/billing/usage?email=m.chen@acme.com&category=llm_tokens&granularity=hour&start_date=2026-01-27T00:00:00Z&end_date=2026-02-03T00:00:00Z' \
  -H 'Authorization: Bearer YOUR_TOKEN'

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

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

import requests

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

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

# Example: all LLM usage for January, grouped by month
usage = get_all_usage(
    start_date="2026-01-01T00:00:00Z",
    end_date="2026-02-01T00:00:00Z",
    granularity="month",
    category="llm_tokens",
)

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

async function getUsage(params = {}) {
  const query = new URLSearchParams(params).toString();
  const res = await fetch(`${BASE}/usage?${query}`, {
    headers: { Authorization: `Bearer ${TOKEN}` },
  });
  return res.json();
}

// Example: top spenders this month
const data = await getUsage({
  granularity: "month",
  sort: "-acu",
  page_size: 10,
});