Usage and Billing APIs

The TeamoRouter usage and billing APIs let you retrieve token usage and charges for individual model requests, aggregate usage and billing over a time range, and check the current account balance.

API overview

Getting started

Base URL

Use the API Base URL shown in the TeamoRouter console. The examples below refer to it as $TEAMO_BASE_URL:

export TEAMO_BASE_URL="https://teamorouter.com"

Authentication

Send your TeamoRouter API key in the Authorization header of every request:

Authorization: Bearer sk-teamo-xxx

Keep your API key secure. Do not include it in frontend code, public repositories, or logs. All keys and IDs in the examples are fictional.

Retrieve usage and billing for a single request

Use a request ID to retrieve the token usage and final charge for one model call.

GET /v1/billing/requests/{request_id}

Path parameters

Request example

curl "$TEAMO_BASE_URL/v1/billing/requests/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

Response example

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": 1784081234,
  "model": "gpt-5.4",
  "usage": {
    "input_tokens": 1000,
    "output_tokens": 500,
    "cached_write_tokens": 800,
    "cached_read_tokens": 200,
    "total_tokens": 2500
  },
  "amount": {
    "value": "0.012680",
    "currency": "USD"
  }
}

Token fields

Token categories that do not apply or are not provided by the upstream service return 0.

Retrieve billing for a time range

Retrieve billing totals for the authenticated API key over a time range. The basic response contains aggregate data only, not individual request records.

GET /v1/billing/costs

Query parameters

The query range must not exceed 90 days. Longer ranges return 400 invalid_request.

Request example

curl "$TEAMO_BASE_URL/v1/billing/costs?start_time=1784044800&end_time=1784131200" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

Response example

{
  "start_time": 1784044800,
  "end_time": 1784131200,
  "total_amount": {
    "value": "1.280000",
    "currency": "USD"
  },
  "requests": 86
}

Retrieve token usage for a time range

Retrieve aggregate token usage for the authenticated API key over a time range.

GET /v1/usage

Query parameters

The query range must not exceed 90 days. Longer ranges return 400 invalid_request.

Request example

curl "$TEAMO_BASE_URL/v1/usage?start_time=1784044800&end_time=1784131200" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

Response example

{
  "start_time": 1784044800,
  "end_time": 1784131200,
  "usage": {
    "input_tokens": 120000,
    "output_tokens": 30000,
    "cached_write_tokens": 10000,
    "cached_read_tokens": 80000,
    "total_tokens": 240000
  },
  "requests": 86
}

Retrieve the account balance

Retrieve the available balance for the account associated with the current API key.

GET /v1/billing/balance

This endpoint does not accept query parameters. The API key identifies the account.

Request example

curl "$TEAMO_BASE_URL/v1/billing/balance" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

Response example

{
  "balance": {
    "value": "85.320000",
    "currency": "USD"
  }
}

Error handling

When an API call fails, the response body contains a stable error code and a message that helps diagnose the problem.

{
  "error": {
    "code": "invalid_request",
    "message": "end_time must be greater than start_time"
  }
}

Common error codes

Recommendations

• Use the same start_time and end_time when reconciling usage and billing so both queries use the same scope.
• Prices may change. Use the amount returned with historical billing records instead of recalculating past charges from the current price list.
• Configure reasonable timeouts and retries. Use exponential backoff for 429 and 5xx responses.