usage/v1

One model call, as it was counted and charged (coordinator/pricing-protocol.md; Elco, 10 Nov: "count usage like pros"): NEAR AI's own id for the call, the tokens it reported, the list price they were counted at, what the person was charged, and NEAR AI's own bill once it's known. Kept for every call; only billed_usd and reconciled_at are filled in later.

Fields

Field	Type or allowed values	Presence in its parent	Description
petal	"usage/v1"	Required
call	string / null	Required	NEAR AI's inference id for the call (its inference-id header, the id its billing knows), or null when there is none
completion	string	Required	the answer's own id
run	string	Required	the conversation it was part of
at	string	Required
model	string	Required	what answered
tokens	object	Required
tokens.in	integer	Required	input tokens, cached ones included
tokens.cached	integer	Required	of in, the ones NEAR AI read from its cache
tokens.out	integer	Required
list_price	object	Required	dollars per million tokens it was counted at
list_price.in	number	Required
list_price.cached	number	Required
list_price.out	number	Required
computed_usd	number	Required	tokens times list price
failed_usd	number	Required	what attempts that failed before this answer were counted at
charged_usd	number	Required	what was taken for it when it answered: computed plus failed
billed_usd	number / null	Required	NEAR AI's own bill for the call, once known; the difference from computed is given back or charged, as its own entry
reconciled_at	string / null	Required

Examples

usage.v1.json

Fixture source

{
  "petal": "usage/v1",
  "call": "d8761185-1b42-59a2-95d0-4d795be9d270",
  "completion": "chatcmpl-6f4df516-c671-48f1-9a37-87acab6046cf",
  "run": "9c599a61de1337853b111b4e",
  "at": "2026-11-10T18:06:55.743Z",
  "model": "deepseek-ai/DeepSeek-V4.1-Flash-1017",
  "tokens": {
    "in": 25510,
    "cached": 24320,
    "out": 311
  },
  "list_price": {
    "in": 0.3,
    "cached": 0.006,
    "out": 1.2
  },
  "computed_usd": 0.000877,
  "failed_usd": 0,
  "charged_usd": 0.000877,
  "billed_usd": 0.000432744,
  "reconciled_at": "2026-11-10T18:07:02.000Z"
}

Full schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:petal:schema:usage:v1",
  "title": "Petal usage v1",
  "description": "One model call, as it was counted and charged (coordinator/pricing-protocol.md; Elco, 10 Nov: \"count usage like pros\"): NEAR AI's own id for the call, the tokens it reported, the list price they were counted at, what the person was charged, and NEAR AI's own bill once it's known. Kept for every call; only billed_usd and reconciled_at are filled in later.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "petal",
    "call",
    "completion",
    "run",
    "at",
    "model",
    "tokens",
    "list_price",
    "computed_usd",
    "failed_usd",
    "charged_usd",
    "billed_usd",
    "reconciled_at"
  ],
  "properties": {
    "petal": {
      "const": "usage/v1"
    },
    "call": {
      "description": "NEAR AI's inference id for the call (its inference-id header, the id its billing knows), or null when there is none",
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "completion": {
      "description": "the answer's own id",
      "type": "string",
      "minLength": 1
    },
    "run": {
      "description": "the conversation it was part of",
      "type": "string",
      "minLength": 1
    },
    "at": {
      "type": "string",
      "format": "date-time"
    },
    "model": {
      "description": "what answered",
      "type": "string",
      "minLength": 1
    },
    "tokens": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "in",
        "cached",
        "out"
      ],
      "properties": {
        "in": {
          "description": "input tokens, cached ones included",
          "type": "integer",
          "minimum": 0
        },
        "cached": {
          "description": "of in, the ones NEAR AI read from its cache",
          "type": "integer",
          "minimum": 0
        },
        "out": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "list_price": {
      "description": "dollars per million tokens it was counted at",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "in",
        "cached",
        "out"
      ],
      "properties": {
        "in": {
          "type": "number",
          "minimum": 0
        },
        "cached": {
          "type": "number",
          "minimum": 0
        },
        "out": {
          "type": "number",
          "minimum": 0
        }
      }
    },
    "computed_usd": {
      "description": "tokens times list price",
      "type": "number",
      "minimum": 0
    },
    "failed_usd": {
      "description": "what attempts that failed before this answer were counted at",
      "type": "number",
      "minimum": 0
    },
    "charged_usd": {
      "description": "what was taken for it when it answered: computed plus failed",
      "type": "number",
      "minimum": 0
    },
    "billed_usd": {
      "description": "NEAR AI's own bill for the call, once known; the difference from computed is given back or charged, as its own entry",
      "type": [
        "number",
        "null"
      ],
      "minimum": 0
    },
    "reconciled_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    }
  }
}