{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/last-price-ai/json-schema/last-price-ai-usage-event-schema.json",
  "title": "UsageEvent",
  "x-generated": "2026-11-15",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/last-price-ai-openapi.json#/components/schemas/UsageEvent",
  "type": "object",
  "properties": {
    "mcp_reason": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 512,
      "description": "Explicit hosted MCP caller rationale, pattern-redacted. Only returned for the viewer's own workspace ledger."
    },
    "mcp_trace_id": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{32}$",
      "description": "Optional trace correlation id. Does not prove identity or backend retention."
    },
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "tenant_id": {
      "x-lastprice-term": "lp:workspace",
      "type": "string",
      "format": "uuid"
    },
    "function_id": {
      "type": "string",
      "format": "uuid"
    },
    "request_id": {
      "type": "string",
      "format": "uuid"
    },
    "input_units": {
      "type": "integer"
    },
    "output_units": {
      "type": "integer"
    },
    "compute_duration_ms": {
      "type": "number"
    },
    "cost": {
      "type": "number"
    },
    "routing_strategy": {
      "type": [
        "string",
        "null"
      ]
    },
    "cached": {
      "type": "boolean"
    },
    "metadata": {
      "type": "object"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "product_type": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "saas",
        "ecommerce",
        "marketplace",
        "digital",
        "api",
        "custom"
      ],
      "description": "The kind of thing that was priced: the context.product_type the request was priced with, recorded when the event was created (so `custom` for a compute call that omitted it, the documented default). Null for events recorded before this field existed and for events whose pricing applied no product type."
    },
    "confidence": {
      "x-lastprice-term": "lp:confidence.quote",
      "type": [
        "number",
        "null"
      ],
      "minimum": 0,
      "maximum": 1,
      "description": "The response's confidence at creation time. Null for events recorded before this field existed (migration 056) and for events recorded without one. Aggregated across a function's events into GET /api/public/leaderboard's avg_confidence."
    },
    "outcome": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "accepted",
        "rejected"
      ],
      "description": "Whether the price this event produced was actually used, as reported via PATCH /api/usage/events/{id}/outcome. Null means not yet reported, not rejected."
    },
    "quality_score": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0,
      "maximum": 1,
      "description": "Caller-reported quality of the price, 0 to 1. Null means not reported."
    },
    "outcome_recorded_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When outcome or quality_score was last recorded. Null until either is."
    },
    "buyer_type": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "agent",
        "person",
        null
      ],
      "description": "Who the price was for, as the request's buyer_type said. Null when the request did not say, and for events recorded before it existed."
    },
    "quote_valid_until": {
      "type": "string",
      "format": "date-time",
      "description": "When the price stopped being good to quote or charge, as the response said in `valid_until`. Present only on events priced while quote expiry was on for the workspace."
    },
    "buyer_agent": {
      "allOf": [
        {
          "$ref": "#/$defs/BuyerAgent"
        }
      ],
      "nullable": true,
      "description": "The buying agent the logged quote names, where a signal named one. Null when it names none, while the buyer-agent-identity release flag is off, and for events recorded before it existed."
    },
    "agent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "The agent the request's credential is bound to (an agent-bound API key or an agent JWT). Null for a key not bound to an agent, for a keyless request, and for events recorded before attribution."
    },
    "agent_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "The agent's name, resolved from this tenant's own agents. Returned by GET /api/usage/events."
    },
    "channel": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "api",
        "demo",
        "mcp"
      ],
      "description": "How the request arrived: the API, the public demo, or the MCP endpoint. Null for events recorded before attribution."
    },
    "auth": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "api_key",
        "jwt",
        "session",
        "embed_token",
        "tenant_header",
        "none",
        "x402"
      ],
      "description": "Which credential carried the request. `none` is a keyless request; `x402` is a pay-per-call request paid with an x402 payment and no credential. Null for events recorded before attribution."
    },
    "payer": {
      "type": [
        "string",
        "null"
      ],
      "description": "Only on an `x402` event: the wallet address that paid, lower-cased. Null otherwise."
    },
    "paid_via": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "x402",
        "day_pass",
        "balance"
      ],
      "description": "How the call was already paid for, when it was: `x402` paid per call with an x402 payment, `day_pass` taken from a day pass the workspace bought, `balance` drawn from the workspace's prepaid balance. Such a call still counts as a request, and its cost is reported, but it is left out of billable_cost and current_period_cost on GET /api/usage so it is never billed again. Null for a call that was not paid for (including one covered by a free daily allowance) and for events recorded before this field existed, except `x402` events, which always read `x402`."
    },
    "user_agent": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 200,
      "description": "The caller's User-Agent, control characters removed and cut to 200 characters. Sent with this tenant's credential or tester tag it is the tenant's own label; otherwise it is an unverified hint. No address is recorded."
    },
    "origin": {
      "type": "string",
      "enum": [
        "mine",
        "testers",
        "others"
      ],
      "description": "Returned by GET /api/usage/events. `mine` when the request carried this tenant's own credential, whether or not it is bound to an agent; `testers` when it was keyless and carried this tenant's private tester tag; `others` otherwise. Decided by what the server verified, never by the User-Agent."
    },
    "origin_reason": {
      "type": "string",
      "enum": [
        "agent",
        "credential",
        "tester_tag",
        "keyless",
        "other_tenant"
      ],
      "description": "Returned by GET /api/usage/events. Why `origin` is what it is: an agent-bound credential, another credential of this tenant, this tenant's tester tag, no credential, or another tenant's credential."
    },
    "experiment": {
      "type": "object",
      "required": [
        "experiment_id",
        "variant",
        "source"
      ],
      "description": "Returned by GET /api/usage/events where recording experiment calls is released for the workspace, and only on an event whose call was recorded in one of the workspace's experiments: the experiment key, the arm, and what recorded it (the Elo A/B test built-in, or a routing policy running the experiment). The Usage page links it to the experiment, whose recorded calls link back here.",
      "properties": {
        "experiment_id": {
          "type": "string",
          "description": "The experiment key."
        },
        "variant": {
          "type": "string",
          "description": "The arm the call was assigned."
        },
        "source": {
          "type": "string",
          "enum": [
            "lastprice/elo-ab-test",
            "lastprice/routing-policy"
          ]
        }
      }
    }
  },
  "$defs": {
    "BuyerAgent": {
      "type": "object",
      "description": "The agent a price was for. `verified` is true only for `agentid` (an AgentID ID token the buying agent sent in the `AgentID-Token` header, checked against AgentID's published keys) and `web_bot_auth` (a Web Bot Auth request signature, checked against the key directory its `Signature-Agent` names). Every other source is what the request said about itself, so it is false.",
      "required": [
        "name",
        "source",
        "verified"
      ],
      "properties": {
        "name": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 100,
          "description": "A short label (a host such as `agent.example.com`, or `chatgpt`), or null when the signal names nobody."
        },
        "source": {
          "type": "string",
          "enum": [
            "declared",
            "ucp_agent",
            "signature_agent",
            "user_agent",
            "agentid",
            "web_bot_auth"
          ],
          "description": "Where the name came from: the request's declared `buyer_agent`, a store order's sales channel, the buyer's agent's own headers (`UCP-Agent`, `Signature-Agent`, `User-Agent`, read on `POST /api/ucp/quote` and `POST /api/ucp/checkout-sessions`), a checked AgentID token (`agentid`), or a checked Web Bot Auth signature (`web_bot_auth`, named by the key directory's host)."
        },
        "verified": {
          "type": "boolean",
          "description": "True only for `agentid` and `web_bot_auth`."
        },
        "subject": {
          "type": "string",
          "maxLength": 128,
          "description": "`agentid`: the stable AgentID of the agent (the token `sub`). `web_bot_auth`: the signing key's `keyid` (its JWK thumbprint)."
        },
        "owner": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 128,
          "description": "`agentid` only: who the agent acts for (`owner_sub`), or null when the token named nobody."
        }
      }
    }
  }
}