gh-aw-firewall/schemas/token-usage.schema.json at main · github/gh-aw-firewall · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
{
  "$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",
    "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."
    },
    "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
    }
  }
}