token-usage.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/github/gh-aw-firewall/main/schemas/token-usage.schema.json",
  "title": "AWF Token Usage Record",
  "description": "A single per-API-call token usage record emitted to token-usage.jsonl by the AWF api-proxy sidecar.",
  "type": "object",
  "required": [
    "_schema",
    "timestamp",
    "event",
    "request_id",
    "provider",
    "model",
    "path",
    "status",
    "streaming",
    "input_tokens",
    "output_tokens",
    "cache_read_tokens",
    "cache_write_tokens",
    "duration_ms"
  ],
  "additionalProperties": true,
  "properties": {
    "_schema": {
      "type": "string",
      "pattern": "^token-usage/v\\d+\\.\\d+\\.\\d+(-\\w+)?$",
      "description": "Schema identifier and version for this record (e.g. \"token-usage/v0.26.0\"). Dev builds use \"token-usage/v0.0.0-dev\"."
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp of when the API call completed."
    },
    "event": {
      "type": "string",
      "const": "token_usage",
      "description": "Stable event discriminator for token usage records."
    },
    "request_id": {
      "type": "string",
      "description": "Unique identifier for this API request (UUID or provider-assigned ID)."
    },
    "provider": {
      "type": "string",
      "enum": [
        "anthropic",
        "openai",
        "copilot",
        "gemini",
        "opencode",
        "unknown"
      ],
      "description": "LLM provider that handled this request."
    },
    "model": {
      "type": "string",
      "description": "Model name returned by the provider (e.g. 'gpt-4o', 'claude-sonnet-4-20250514')."
    },
    "path": {
      "type": "string",
      "description": "API endpoint path for this request (e.g. '/v1/messages', '/v1/chat/completions')."
    },
    "status": {
      "type": "integer",
      "minimum": 100,
      "maximum": 599,
      "description": "HTTP response status code returned by the provider."
    },
    "streaming": {
      "type": "boolean",
      "description": "Whether the response was a streaming (SSE) response."
    },
    "input_tokens": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of input/prompt tokens consumed."
    },
    "output_tokens": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of output/completion tokens generated."
    },
    "cache_read_tokens": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of tokens read from the provider's prompt cache (Anthropic cache_read_input_tokens or OpenAI cached_tokens)."
    },
    "cache_write_tokens": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of tokens written to the provider's prompt cache (Anthropic cache_creation_input_tokens)."
    },
    "duration_ms": {
      "type": "number",
      "minimum": 0,
      "description": "End-to-end request duration in milliseconds."
    },
    "response_bytes": {
      "type": "integer",
      "minimum": 0,
      "description": "Total number of bytes in the response body (optional, omitted for WebSocket upgrades)."
    },
    "x_initiator": {
      "type": "string",
      "enum": [
        "agent",
        "user"
      ],
      "description": "The X-Initiator header value sent on the request. Determines billing treatment: 'agent' requests are not billed as premium, 'user' requests are. Present only for Copilot-bound requests."
    },
    "billing": {
      "type": "object",
      "description": "Billing/quota information extracted from upstream response headers (X-Quota-Snapshot-*, X-RateLimit-*). Present only when the upstream returns billing headers.",
      "properties": {
        "quota_chat": {
          "type": "object",
          "description": "X-Quota-Snapshot-Chat parsed fields.",
          "properties": {
            "ent": {
              "type": "string",
              "description": "Entitlement count (-1 = unlimited)."
            },
            "ov": {
              "type": "string",
              "description": "Overage requests made this period."
            },
            "ovPerm": {
              "type": "string",
              "description": "Whether overage is allowed (true/false)."
            },
            "rem": {
              "type": "string",
              "description": "Percentage of entitlement remaining."
            },
            "rst": {
              "type": "string",
              "description": "Quota reset date (RFC 3339 UTC)."
            }
          },
          "additionalProperties": true
        },
        "quota_premium-chat": {
          "type": "object",
          "description": "X-Quota-Snapshot-Premium-Chat parsed fields. Tracks premium request units (PRU).",
          "properties": {
            "ent": {
              "type": "string",
              "description": "Premium entitlement count."
            },
            "ov": {
              "type": "string",
              "description": "Premium overage requests made."
            },
            "ovPerm": {
              "type": "string",
              "description": "Whether premium overage is allowed."
            },
            "rem": {
              "type": "string",
              "description": "Percentage of premium entitlement remaining."
            },
            "rst": {
              "type": "string",
              "description": "Premium quota reset date."
            }
          },
          "additionalProperties": true
        },
        "rate_limit": {
          "type": "string",
          "description": "X-RateLimit-Limit value."
        },
        "rate_remaining": {
          "type": "string",
          "description": "X-RateLimit-Remaining value."
        },
        "rate_reset": {
          "type": "string",
          "description": "X-RateLimit-Reset value (Unix timestamp)."
        }
      },
      "additionalProperties": true
    },
    "ai_credits_accounting_policy": {
      "type": "string",
      "description": "Accounting policy applied when resolving pricing for this model (e.g. 'concrete_model', 'unknown_model_fallback', 'dynamic_selector_runtime', 'dynamic_selector_fallback'). Present only when apiProxy.maxAiCredits is configured."
    },
    "ai_credits_dynamic_selector": {
      "type": "string",
      "description": "Name of the dynamic model selector used to resolve pricing. Present only when apiProxy.maxAiCredits is configured and the model was routed through a dynamic selector."
    },
    "ai_credits_fallback_pricing_used": {
      "type": "boolean",
      "description": "Whether fallback pricing was used to compute AI credits for this call. Present only when apiProxy.maxAiCredits is configured."
    },
    "ai_credits_pricing_api_version": {
      "type": "string",
      "description": "API version of the pricing data source used to resolve this model's cost, when known. Present only when apiProxy.maxAiCredits is configured and the pricing source reports a version."
    },
    "ai_credits_pricing_discount_percent": {
      "type": "number",
      "minimum": 0,
      "maximum": 100,
      "description": "Promotional discount percentage applied to this model's pricing, when known. Present only when apiProxy.maxAiCredits is configured and a promotion is active."
    },
    "ai_credits_pricing_observed_at": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp (ISO 8601) at which the pricing data used for this call was observed/fetched, when known. Present only when apiProxy.maxAiCredits is configured."
    },
    "ai_credits_pricing_source": {
      "type": "string",
      "description": "Source of the pricing data used to compute AI credits (e.g. 'curated', 'models.dev', 'configured_default', 'builtin_fallback'). Present only when apiProxy.maxAiCredits is configured."
    },
    "ai_credits_pricing_tier": {
      "type": "string",
      "description": "Pricing tier applied when resolving cost for this model (e.g. 'default', 'conservative'). Present only when apiProxy.maxAiCredits is configured."
    },
    "ai_credits_this_response": {
      "type": "number",
      "minimum": 0,
      "description": "AI credits consumed by this API call. Computed from token counts and per-model pricing. Present only when apiProxy.maxAiCredits is configured."
    },
    "ai_credits_total": {
      "type": "number",
      "minimum": 0,
      "description": "Cumulative AI credits consumed since the start of the run. Present only when apiProxy.maxAiCredits is configured."
    },
    "effective_tokens_this_response": {
      "type": "number",
      "minimum": 0,
      "description": "Weighted effective tokens consumed by this API call (input×1 + cache_read×0.1 + output×4 + reasoning×4), scaled by the model multiplier. Present only when apiProxy.maxEffectiveTokens is configured."
    },
    "effective_tokens_total": {
      "type": "number",
      "minimum": 0,
      "description": "Cumulative weighted effective tokens consumed since the start of the run. Present only when apiProxy.maxEffectiveTokens is configured."
    },
    "model_multiplier": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Per-model cost multiplier applied to the effective token calculation for this request. Present only when apiProxy.maxEffectiveTokens is configured."
    },
    "reasoning_tokens": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of reasoning/thinking tokens consumed (e.g. OpenAI o-series completion_tokens_details.reasoning_tokens, Anthropic thinking blocks, or Gemini thoughtsTokenCount). Zero when the model does not emit reasoning tokens."
    }
  }
}