{
  "$id": "maple-usage-record.v2.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": true,
  "description": "One line of the usage log (JSON Lines). Later versions may add properties; none is ever renamed, removed or retyped.",
  "properties": {
    "agent": {
      "type": "string",
      "description": "The kind of client, from its User-Agent: claude-code, opencode, maple-harness or other. May be left out; absent means unknown."
    },
    "ai_units": {
      "type": "number",
      "minimum": 0,
      "description": "What the request cost in the provider's own units, when it reports them. Local models report none. Unit: AI units. May be left out; absent means 0."
    },
    "at": {
      "type": "string",
      "format": "date-time",
      "description": "When the request was recorded (UTC, RFC 3339 text)."
    },
    "cache_class": {
      "type": "string",
      "description": "How the provider's prompt cache did: hit, partial, miss, lost or n/a. May be left out; absent means not classified."
    },
    "cache_reason": {
      "type": "string",
      "description": "For a miss or a loss, a short reason. May be left out; absent means no reason given."
    },
    "cache_saved_estimated": {
      "type": "number",
      "description": "Estimated: what the provider's prompt cache saved on this request, against paying for the same tokens without the cache. Unit: AI units. May be left out; absent means 0. Added in schema version 2: lines written before it do not have it."
    },
    "cache_write_surcharge_estimated": {
      "type": "number",
      "minimum": 0,
      "description": "Estimated: what writing to the prompt cache cost on this request above that same price. Unit: AI units. May be left out; absent means 0. Added in schema version 2: lines written before it do not have it."
    },
    "cache_write_tokens": {
      "type": "integer",
      "minimum": 0,
      "description": "Input tokens written to the provider's prompt cache (0 when the provider reports none). Unit: tokens."
    },
    "cached_tokens": {
      "type": "integer",
      "minimum": 0,
      "description": "Input tokens read from the provider's prompt cache (0 when the provider reports none). Unit: tokens."
    },
    "client": {
      "type": "string",
      "description": "The access token's label, or local for a caller on this machine without one (never the token itself). May be left out; absent means unknown."
    },
    "conv": {
      "type": "string",
      "description": "An opaque label grouping the requests of one conversation (never content). May be left out; absent means unknown."
    },
    "cost_currency": {
      "type": "string",
      "description": "The currency of cost_estimated, such as USD. May be left out; absent means no estimate. Added in schema version 2: lines written before it do not have it."
    },
    "cost_estimated": {
      "type": "number",
      "minimum": 0,
      "description": "An estimate of what the request cost at the provider's published list prices, from a provider set up to give one. Not a bill, and separate from ai_units: never add the two together. Unit: cost_currency. May be left out; absent means no estimate. Added in schema version 2: lines written before it do not have it."
    },
    "duration_ms": {
      "type": "integer",
      "minimum": 0,
      "description": "How long the request took. Unit: milliseconds."
    },
    "error": {
      "type": "string",
      "description": "Why the request failed, if it did. May be left out; absent means no error."
    },
    "fallback": {
      "type": "boolean",
      "description": "Whether the request was answered by a fallback after the first choice failed. May be left out; absent means false."
    },
    "images_cost_estimated": {
      "type": "number",
      "minimum": 0,
      "description": "Estimated: the prompt-cache rewrite a newly replaced image cost on this request. Unit: AI units. May be left out; absent means 0. Added in schema version 2: lines written before it do not have it."
    },
    "images_saved_estimated": {
      "type": "number",
      "minimum": 0,
      "description": "Estimated: what sending fewer image tokens saved on this request. Unit: AI units. May be left out; absent means 0. Added in schema version 2: lines written before it do not have it."
    },
    "images_saved_tokens_estimated": {
      "type": "integer",
      "minimum": 0,
      "description": "Estimated from each provider's published image formula: image tokens avoided by resizing or replacing images in this request. Unit: tokens. May be left out; absent means 0. Added in schema version 2: lines written before it do not have it."
    },
    "input_tokens": {
      "type": "integer",
      "minimum": 0,
      "description": "Input tokens, as the provider reported them. Unit: tokens."
    },
    "messages": {
      "type": "integer",
      "minimum": 0,
      "description": "Messages in the request. Unit: count."
    },
    "model": {
      "type": "string",
      "description": "The model that answered."
    },
    "output_tokens": {
      "type": "integer",
      "minimum": 0,
      "description": "Output tokens, as the provider reported them. Unit: tokens."
    },
    "prefix": {
      "type": "string",
      "description": "An opaque grouping label (never content). May be left out; absent means unknown."
    },
    "priced": {
      "type": "boolean",
      "description": "Whether the proxy could put an AI-unit value on this request's savings, which needs a few earlier requests to the same model. When false, the AI-unit savings columns are 0 because nothing was valued, not because nothing was saved. May be left out; absent means false. Added in schema version 2: lines written before it do not have it."
    },
    "provider": {
      "type": "string",
      "description": "The provider that answered."
    },
    "requested": {
      "type": "string",
      "description": "The model name the client asked for (may be a routing alias such as auto)."
    },
    "schema_version": {
      "type": "integer",
      "minimum": 0,
      "description": "The schema version the line was written with. May be left out; absent means 1. Added in schema version 2: lines written before it do not have it."
    },
    "session": {
      "type": "string",
      "description": "An opaque id a client sends to group its requests into one session; Maple Harness sends its session's id (never content). May be left out; absent means unknown. Added in schema version 2: lines written before it do not have it."
    },
    "setup": {
      "type": "string",
      "description": "An opaque grouping label (never content). May be left out; absent means unknown."
    },
    "snapshots_cost_estimated": {
      "type": "number",
      "minimum": 0,
      "description": "Estimated: a request that only asked again for a snapshot straight after a trimmed one. Unit: AI units. May be left out; absent means 0. Added in schema version 2: lines written before it do not have it."
    },
    "snapshots_saved_estimated": {
      "type": "number",
      "minimum": 0,
      "description": "Estimated: what leaving those snapshot tokens out saved on this request. Unit: AI units. May be left out; absent means 0. Added in schema version 2: lines written before it do not have it."
    },
    "snapshots_saved_tokens_estimated": {
      "type": "integer",
      "minimum": 0,
      "description": "Estimated (characters divided by four): tokens left out of browser page snapshots in this request. Unit: tokens. May be left out; absent means 0. Added in schema version 2: lines written before it do not have it."
    },
    "stabiliser_saved_estimated": {
      "type": "number",
      "description": "Estimated: what the prefix stabiliser saved on this request. Shown on the Savings card on its own line, not in its headline. Unit: AI units. May be left out; absent means 0. Added in schema version 2: lines written before it do not have it."
    },
    "streamed": {
      "type": "boolean",
      "description": "Whether the answer was streamed."
    },
    "surface": {
      "type": "string",
      "description": "The API the caller used: chat (OpenAI-compatible) or messages (Anthropic-compatible). May be left out; absent means unknown."
    },
    "tools": {
      "type": "integer",
      "minimum": 0,
      "description": "Tool definitions sent with the request. Unit: count."
    },
    "trim_cost_estimated": {
      "type": "number",
      "minimum": 0,
      "description": "Estimated: what trimming cost on this request: rewriting the prompt cache after a batch of trimming, and a request that only repeated a call whose result was trimmed. Unit: AI units. May be left out; absent means 0. Added in schema version 2: lines written before it do not have it."
    },
    "trim_saved_estimated": {
      "type": "number",
      "description": "Estimated: what trimming saved on this request, valued at the price of a cached token, the lowest a resent token can cost. Negative when the model asked again for a trimmed result and an earlier saving was taken back. Unit: AI units. May be left out; absent means 0. Added in schema version 2: lines written before it do not have it."
    },
    "trim_saved_tokens_estimated": {
      "type": "integer",
      "minimum": 0,
      "description": "Estimated from their length: tokens that trimming left out of this request. Unit: tokens. May be left out; absent means 0. Added in schema version 2: lines written before it do not have it."
    },
    "warming": {
      "type": "boolean",
      "description": "Whether the proxy sent this request itself, to keep a provider's prompt cache from expiring while a conversation was idle. What it cost is in ai_units. May be left out; absent means false. Added in schema version 2: lines written before it do not have it."
    },
    "warming_expected_saved_estimated": {
      "type": "number",
      "minimum": 0,
      "description": "Estimated, on a cache-warming request: the saving expected when it was sent, not a confirmed outcome. Shown on the Savings card on its own line, not in its headline. Unit: AI units. May be left out; absent means 0. Added in schema version 2: lines written before it do not have it."
    }
  },
  "required": [
    "at",
    "duration_ms",
    "requested",
    "model",
    "provider",
    "streamed",
    "tools",
    "messages",
    "input_tokens",
    "output_tokens",
    "cached_tokens",
    "cache_write_tokens"
  ],
  "title": "Maple usage record, schema version 2",
  "type": "object"
}
