List usage events

curl "https://api.tokenpath.ai/v1/me/usage?limit=20" \
  -H "Authorization: Bearer $TOKENPATH_API_KEY"

import os
import httpx

events = httpx.get(
    "https://api.tokenpath.ai/v1/me/usage",
    headers={"Authorization": f"Bearer {os.environ['TOKENPATH_API_KEY']}"},
    params={"limit": 1000},
).json()["events"]

spent = sum(e["actual_cost_micros"] for e in events if e["status"] == "settled")
print(f"Spent ${spent / 1_000_000:.4f} across the last {len(events)} events")

{
  "events": [
    {
      "event_id": "evt_a1b2c3d4e5f6_reserved",
      "customer_id": "cus_abc123",
      "api_key_id": "key_xyz789",
      "request_id": "req_a1b2c3d4e5f6",
      "estimated_tokens": 69,
      "estimated_cost_micros": 69,
      "actual_tokens": null,
      "actual_cost_micros": null,
      "billing_mode": "enforced",
      "status": "reserved",
      "reason": "credits_reserved"
    },
    {
      "event_id": "evt_a1b2c3d4e5f6_settled",
      "customer_id": "cus_abc123",
      "api_key_id": "key_xyz789",
      "request_id": "req_a1b2c3d4e5f6",
      "estimated_tokens": 69,
      "estimated_cost_micros": 69,
      "actual_tokens": 96,
      "actual_cost_micros": 96,
      "billing_mode": "enforced",
      "status": "settled",
      "reason": "gpu_succeeded"
    }
  ]
}

GET https://api.tokenpath.ai/v1/me/usage

Returns your most recent billing events, oldest first. Use it to audit spend, reconcile invoices, or look up what one request cost. Requires the usage:read scope.

Query parameters

integer

default:"100"

How many of the most recent events to return, from 1 to 1000.

Response

array of object

Billing events, oldest first.

Show properties

string

Unique ID for this event.

string

Your account ID.

string

The key that made the request.

string

The billing ID of the request. All events for one API call share it.

integer

The pre-run estimate that sized the hold.

integer

The estimate in microdollars. Divide by 1,000,000 to get USD.

integer | null

Tokens charged. Set on settled events, null otherwise.

integer | null

The charge in microdollars. Set on settled events, null otherwise.

"enforced" | "observe"

enforced means credits were held and charged. observe means usage was recorded without moving credits.

string

What happened. See the table below.

string

A machine-readable detail, such as credits_reserved, gpu_succeeded, request_cancelled, insufficient_credits, or generation_dispatched.

`status`	Meaning
`reserved`	Credits were held when a request started.
`settled`	The request succeeded and `actual_tokens` were charged. The rest of the hold was returned.
`released`	The request failed or was cancelled, and the whole hold was returned.
`rejected`	The request was refused before running, usually for `insufficient_credits`.
`observed`	Usage was recorded on an account where billing is not enforced.
`starter_grant`	Free starter credits were added to a new account.
`purchase`	Purchased credits were added.
`subscription_cycle`	A subscription allowance was reset for a new billing cycle.

Each state change is a separate event. A successful request shows up as a reserved event followed by a settled event with the same request_id.

curl "https://api.tokenpath.ai/v1/me/usage?limit=20" \
  -H "Authorization: Bearer $TOKENPATH_API_KEY"

import os
import httpx

events = httpx.get(
    "https://api.tokenpath.ai/v1/me/usage",
    headers={"Authorization": f"Bearer {os.environ['TOKENPATH_API_KEY']}"},
    params={"limit": 1000},
).json()["events"]

spent = sum(e["actual_cost_micros"] for e in events if e["status"] == "settled")
print(f"Spent ${spent / 1_000_000:.4f} across the last {len(events)} events")

{
  "events": [
    {
      "event_id": "evt_a1b2c3d4e5f6_reserved",
      "customer_id": "cus_abc123",
      "api_key_id": "key_xyz789",
      "request_id": "req_a1b2c3d4e5f6",
      "estimated_tokens": 69,
      "estimated_cost_micros": 69,
      "actual_tokens": null,
      "actual_cost_micros": null,
      "billing_mode": "enforced",
      "status": "reserved",
      "reason": "credits_reserved"
    },
    {
      "event_id": "evt_a1b2c3d4e5f6_settled",
      "customer_id": "cus_abc123",
      "api_key_id": "key_xyz789",
      "request_id": "req_a1b2c3d4e5f6",
      "estimated_tokens": 69,
      "estimated_cost_micros": 69,
      "actual_tokens": 96,
      "actual_cost_micros": 96,
      "billing_mode": "enforced",
      "status": "settled",
      "reason": "gpu_succeeded"
    }
  ]
}

Errors

In addition to the authentication errors:

Status	Code	Meaning
`422`	`validation_error`	`limit` is outside 1 to 1000.

curl "https://api.tokenpath.ai/v1/me/usage?limit=20" \
  -H "Authorization: Bearer $TOKENPATH_API_KEY"

import os
import httpx

events = httpx.get(
    "https://api.tokenpath.ai/v1/me/usage",
    headers={"Authorization": f"Bearer {os.environ['TOKENPATH_API_KEY']}"},
    params={"limit": 1000},
).json()["events"]

spent = sum(e["actual_cost_micros"] for e in events if e["status"] == "settled")
print(f"Spent ${spent / 1_000_000:.4f} across the last {len(events)} events")

{
  "events": [
    {
      "event_id": "evt_a1b2c3d4e5f6_reserved",
      "customer_id": "cus_abc123",
      "api_key_id": "key_xyz789",
      "request_id": "req_a1b2c3d4e5f6",
      "estimated_tokens": 69,
      "estimated_cost_micros": 69,
      "actual_tokens": null,
      "actual_cost_micros": null,
      "billing_mode": "enforced",
      "status": "reserved",
      "reason": "credits_reserved"
    },
    {
      "event_id": "evt_a1b2c3d4e5f6_settled",
      "customer_id": "cus_abc123",
      "api_key_id": "key_xyz789",
      "request_id": "req_a1b2c3d4e5f6",
      "estimated_tokens": 69,
      "estimated_cost_micros": 69,
      "actual_tokens": 96,
      "actual_cost_micros": 96,
      "billing_mode": "enforced",
      "status": "settled",
      "reason": "gpu_succeeded"
    }
  ]
}

Overview

Endpoints

Query parameters

Response

Errors

​Query parameters

​Response

​Errors

Query parameters

Response

Errors