Report usage

Baseten meters standard token-based traffic at the Distribution Platform inference gateway. Report usage that only your model can measure, such as usage from streaming, WebSocket, or custom protocol traffic, with the Usage Reporting API. For each inference request attributed to a Distribution Platform customer, Baseten sends a signed identity token in the X-Baseten-Identity-Token header. Copy that token exactly into each usage event. Baseten injects the reporting URL into your model container as the BASETEN_USAGE_ENDPOINT environment variable.

Report one usage event

cURL
Python

To report one token-usage event with cURL:Set BASETEN_IDENTITY_TOKEN to the exact value of the X-Baseten-Identity-Token header from a distribution-attributed request. Set ts to the RFC 3339 timestamp when the usage occurred. Set each usage value to the measured, non-negative delta for this event, not a cumulative total.

curl --silent --show-error \
  --request POST \
  --url "$BASETEN_USAGE_ENDPOINT" \
  --header "Content-Type: application/json" \
  --data '{
    "events": [
      {
        "identity_token": "'"$BASETEN_IDENTITY_TOKEN"'",
        "ts": "2026-07-28T12:00:00Z",
        "usage": {
          "uncached_input_tokens": 9273,
          "cached_input_tokens": 5,
          "output_tokens": 703
        }
      }
    ]
  }'

{
  "accepted": 1,
  "rejected": 0
}

To smoke-test a standalone reporting helper with Python:Set BASETEN_IDENTITY_TOKEN to the exact identity token from a distribution-attributed request before running this standalone script. The script passes the environment-variable value to report_usage; it does not read request headers. The helper constructs the event once, then retries that same payload and timestamp up to three times with backoff for 429 and 5xx responses.

import json
import logging
import os
from typing import Optional

import requests
from requests.adapters import HTTPAdapter
from urllib3.util import Retry

logger = logging.getLogger(__name__)
USAGE_ENDPOINT = os.environ["BASETEN_USAGE_ENDPOINT"]

retry = Retry(
    total=3,
    backoff_factor=0.5,
    status_forcelist=(429, 500, 502, 503, 504),
    allowed_methods=frozenset({"POST"}),
    respect_retry_after_header=True,
    raise_on_status=False,
)
adapter = HTTPAdapter(max_retries=retry)
session = requests.Session()
session.mount("http://", adapter)
session.mount("https://", adapter)


def report_usage(
    identity_token: str,
    ts: str,
    usage: dict[str, int],
) -> Optional[dict]:
    event = {
        "identity_token": identity_token,
        "ts": ts,
        "usage": usage,
    }

    try:
        response = session.post(
            USAGE_ENDPOINT,
            json={"events": [event]},
            timeout=2,
        )
        response.raise_for_status()

        result = response.json()
        if result["rejected"]:
            logger.warning("Usage event rejected: %s", result["results"])
        return result
    except (requests.RequestException, KeyError, ValueError) as error:
        logger.warning("Usage reporting failed after retries: %s", error)
        return None


if __name__ == "__main__":
    result = report_usage(
        identity_token=os.environ["BASETEN_IDENTITY_TOKEN"],
        ts="2026-07-28T12:00:00Z",
        usage={
            "uncached_input_tokens": 9273,
            "cached_input_tokens": 5,
            "output_tokens": 703,
        },
    )
    print(json.dumps(result, indent=2))

{
  "accepted": 1,
  "rejected": 0
}

In a production handler, pass the per-request X-Baseten-Identity-Token value to report_usage after inference succeeds. If the header is absent, skip usage reporting for that request. The helper logs the final failure without failing inference. Monitor this warning so that persistent reporting failures don’t leave usage unreported.

Use supported metrics

Every usage value is a non-negative integer delta for that event, not a cumulative total.

Metric	Unit	Event requirements
`uncached_input_tokens`	Tokens	Can be combined with other token metrics. Defaults to zero when omitted.
`cached_input_tokens`	Tokens	Can be combined with other token metrics. Defaults to zero when omitted.
`output_tokens`	Tokens	Can be combined with other token metrics. Defaults to zero when omitted.
`input_characters`	Characters	Use this as the event’s only metric.
`audio_seconds`	Seconds	Use this as the event’s only metric.
`image_generations`	Images	Use this as the event’s only metric.

A token event includes one or more of uncached_input_tokens, cached_input_tokens, and output_tokens. You can combine token fields, and omitted token fields default to 0. A non-token event uses exactly one of input_characters, audio_seconds, or image_generations. Send separate events for token usage and for each non-token metric type. Baseten sums the deltas from all accepted events for a request or session.

Batch events

A batch can contain events from multiple distribution-attributed inference requests. Each event carries the identity token from its corresponding request. To inspect partial acceptance in a two-event batch: Set FIRST_BASETEN_IDENTITY_TOKEN from a distribution-attributed request. This integration example deliberately uses an invalid identity token for the second event:

SECOND_BASETEN_IDENTITY_TOKEN="invalid-token"

curl --silent --show-error \
  --request POST \
  --url "$BASETEN_USAGE_ENDPOINT" \
  --header "Content-Type: application/json" \
  --data '{
    "events": [
      {
        "identity_token": "'"$FIRST_BASETEN_IDENTITY_TOKEN"'",
        "ts": "2026-07-28T12:00:00Z",
        "usage": {
          "uncached_input_tokens": 9273,
          "cached_input_tokens": 5,
          "output_tokens": 703
        }
      },
      {
        "identity_token": "'"$SECOND_BASETEN_IDENTITY_TOKEN"'",
        "ts": "2026-07-28T12:00:05Z",
        "usage": {
          "audio_seconds": 42
        }
      }
    ]
  }'

{
  "accepted": 1,
  "rejected": 1,
  "results": [
    {
      "index": 1,
      "status": "rejected",
      "error": "invalid identity token"
    }
  ]
}

The endpoint validates events independently. A 200 OK response means the endpoint processed the request envelope, but it may still reject some events. Check rejected and use each entry’s index in results to identify rejected events. results contains only rejected events. A 400 Bad Request response means the request envelope is invalid, such as malformed JSON or an events value that isn’t an array. The endpoint processes no events.

Retry events

In production integrations, always include ts and format it as RFC 3339. It records when the usage occurred and participates in deduplication. Reuse the exact original ts on every retry. If an event omits ts, the server uses its receive time; retrying that event isn’t idempotent and may double-bill the same usage. After partial acceptance, resend only the rejected events. Don’t resend accepted events as part of the retry.

Limits

The JSON request body must not exceed 1 MiB. The endpoint rejects unknown fields: unknown envelope fields invalidate the request, while unknown event fields reject that event independently.

Next steps

Insights: Review customers, models, and estimated gross proceeds associated with accepted usage.
Manage your model: Complete the other requirements before your listing goes live.

Overview

Get started

Model APIs

Inference

Development

Deployment

Engines

Model Labs

Organization

Observability

Troubleshooting

Report one usage event

Use supported metrics

Batch events

Retry events

Limits

Next steps

​Report one usage event

​Use supported metrics

​Batch events

​Retry events

​Limits

​Next steps

Report one usage event

Use supported metrics

Batch events

Retry events

Limits

Next steps