UsageSummary

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hyperresearch-ai/json-schema/hyperresearch-ai-usage-summary-schema.json",
  "title": "UsageSummary",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hyperresearch-ai-openapi.json#/components/schemas/UsageSummary",
  "type": "object",
  "properties": {
    "period": {
      "type": "object",
      "properties": {
        "from": {
          "type": "string"
        },
        "to": {
          "type": "string"
        }
      },
      "required": [
        "from",
        "to"
      ]
    },
    "workspace_id": {
      "type": "string"
    },
    "runs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "tier": {
            "type": "string"
          },
          "runs": {
            "type": "integer",
            "description": "Runs of this tier created in the period."
          },
          "price_cents": {
            "type": "integer",
            "description": "Reserved list price on the control rows. 0 for a run an included (trial) allowance covered — this is NOT what was charged."
          },
          "amount_cents": {
            "type": "integer",
            "description": "What the billing ledger metered for these runs, refunds included. Sums to `totals.run_amount_cents`."
          },
          "metered_runs": {
            "type": "integer",
            "description": "How many of these runs have a ledger row yet. `runs - metered_runs` is the number still in flight."
          },
          "included_runs": {
            "type": "integer",
            "description": "How many of these runs an included (trial) allowance covered, metered at $0."
          },
          "charged_runs": {
            "type": "integer",
            "description": "`runs - included_runs`: the runs no allowance covered."
          },
          "charged_cents": {
            "type": "integer",
            "description": "What the ledger metered for the charged runs alone."
          },
          "included_cents": {
            "type": "integer",
            "description": "What the ledger metered for the included runs. $0 by definition."
          },
          "complimentary_runs": {
            "type": "integer",
            "description": "How many of these runs an operator grant comped (0041). Taken OUT of `charged_runs`, never netted into it."
          },
          "complimentary_cents": {
            "type": "integer",
            "description": "What the comped runs would have cost — the real price, which their ledger rows carry. Not part of `charged_cents`."
          }
        },
        "required": [
          "tier",
          "runs",
          "price_cents",
          "amount_cents",
          "metered_runs",
          "included_runs",
          "charged_runs",
          "charged_cents",
          "included_cents"
        ]
      }
    },
    "charged": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "tier": {
            "type": "string"
          },
          "runs": {
            "type": "integer"
          },
          "amount_cents": {
            "type": "integer"
          },
          "metered_runs": {
            "type": "integer"
          },
          "included_in_trial": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "tier",
          "runs",
          "amount_cents",
          "metered_runs",
          "included_in_trial"
        ]
      },
      "description": "Runs that were billed this period, by tier, with what they cost. `totals.charged_cents` is exactly the sum of these amounts — no other number has to be subtracted to arrive at it (E2E2-07)."
    },
    "included": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "tier": {
            "type": "string"
          },
          "runs": {
            "type": "integer"
          },
          "amount_cents": {
            "type": "integer",
            "description": "Always 0: an included run is not charged."
          },
          "included_in_trial": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "tier",
          "runs",
          "amount_cents",
          "included_in_trial"
        ]
      },
      "description": "Trial-covered runs, listed apart from the charged ones so \"$0.00\" reads as \"included\" rather than as \"free by accident\"."
    },
    "complimentary": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "tier": {
            "type": "string"
          },
          "runs": {
            "type": "integer"
          },
          "amount_cents": {
            "type": "integer",
            "description": "The real price of these runs, which is what their ledger rows carry — a comped run is not a $0 run."
          },
          "complimentary": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "tier",
          "runs",
          "amount_cents",
          "complimentary"
        ]
      },
      "description": "Runs an operator grant comped (0041), listed apart from the charged ones and NOT included in `totals.charged_cents`. Absent when this account has none."
    },
    "metered": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string"
          },
          "quantity": {
            "type": "integer",
            "description": "Net of refunds, like `amount_cents` beside it. To show a quantity next to `events`, use `charges.quantity`: it counts the same population (E2E2-07)."
          },
          "amount_cents": {
            "type": "integer",
            "description": "Net of refunds."
          },
          "events": {
            "type": "integer",
            "description": "The metered events of this kind in the period — charged and included together, refunds excluded. ALWAYS equal to `charges.quantity` for a one-unit-per-event meter such as runs, because they are the same rows counted twice; a row that read `Research runs — 7 — $0.00 — 8 events` was counting a refund as an eighth run (E2E4A-10). Show `charges.amount_cents` beside it for what those events were charged."
          },
          "gross_events": {
            "type": "integer",
            "description": "Every ledger row of this kind, refunds included. `events + refunds.events`."
          },
          "charges": {
            "$ref": "#/$defs/UsageTotals"
          },
          "refunds": {
            "allOf": [
              {
                "$ref": "#/$defs/UsageTotals"
              },
              {
                "description": "The negative rows only; `quantity` and `amount_cents` stay negative. A refund reverses an event, it is not an event, so it is never counted in `events`."
              }
            ]
          }
        },
        "required": [
          "kind",
          "quantity",
          "amount_cents",
          "events",
          "gross_events",
          "charges",
          "refunds"
        ]
      }
    },
    "totals": {
      "type": "object",
      "properties": {
        "amount_cents": {
          "type": "integer",
          "description": "Every metered kind in this workspace for the period."
        },
        "events": {
          "type": "integer"
        },
        "runs": {
          "type": "integer",
          "description": "Runs created in the period, all tiers."
        },
        "metered_runs": {
          "type": "integer"
        },
        "included_runs": {
          "type": "integer"
        },
        "charged_runs": {
          "type": "integer",
          "description": "Runs created in the period that no allowance covered."
        },
        "charged_cents": {
          "type": "integer",
          "description": "What the charged runs cost, and exactly the sum of `charged[].amount_cents`. This is the period total a customer is asked to believe."
        },
        "run_amount_cents": {
          "type": "integer",
          "description": "The run-kind slice of `amount_cents`; equals the sum of `runs[].amount_cents`."
        },
        "complimentary_runs": {
          "type": "integer",
          "description": "Runs created in the period that an operator grant comped (0041)."
        },
        "complimentary_cents": {
          "type": "integer",
          "description": "What those runs would have cost, and exactly the sum of `complimentary[].amount_cents`. Deliberately NOT part of `charged_cents`: the account was not asked to pay it."
        }
      },
      "required": [
        "amount_cents",
        "events",
        "runs",
        "metered_runs",
        "included_runs",
        "charged_runs",
        "charged_cents",
        "run_amount_cents"
      ]
    },
    "licensed_articles": {
      "type": "object",
      "properties": {
        "month": {
          "type": "string",
          "description": "`YYYY-MM`, the month the source ledger books against."
        },
        "articles": {
          "type": "integer",
          "description": "Licensed article purchases attributed to this workspace this month, settled or in flight."
        },
        "settled_micros": {
          "type": "integer",
          "description": "What the vendor confirmed charging, in micro-USD (1000000 = $1.00). Micro-USD and not cents because a licensed page costs $0.001 to $1.00, and most purchases would round to free."
        },
        "reserved_micros": {
          "type": "integer",
          "description": "Booked and not yet settled: a purchase in flight, held at its worst case."
        },
        "unresolved_micros": {
          "type": "integer",
          "description": "Of `reserved_micros`, the part whose outcome is unknown and awaiting reconciliation against the vendor's own record. Reported apart because an unknown outcome is neither confirmed spend nor available headroom."
        }
      },
      "required": [
        "month",
        "articles",
        "settled_micros",
        "reserved_micros",
        "unresolved_micros"
      ],
      "description": "Licensed-article spend (rung `LT`), at cost, from the fetch lane's own source ledger — NOT from `usage_events` and NOT part of `totals`. The two ledgers are separate on purpose: one is what this workspace was charged, the other is what a vendor charged us for a page, and summing them would double-count. All zeros when nothing was licensed, which is the shipping state."
    },
    "account": {
      "type": "object",
      "properties": {
        "plan": {
          "type": "string"
        },
        "spend_cap_cents_month": {
          "type": "integer"
        },
        "month_to_date_cents": {
          "type": "integer",
          "description": "Account-wide charge for the current month, across EVERY workspace of the account — not just this one. Compare with `totals.amount_cents`, which is this workspace only."
        }
      },
      "required": [
        "plan",
        "spend_cap_cents_month",
        "month_to_date_cents"
      ]
    }
  },
  "required": [
    "period",
    "workspace_id",
    "runs",
    "charged",
    "included",
    "metered",
    "totals",
    "licensed_articles",
    "account"
  ],
  "$defs": {
    "UsageTotals": {
      "type": "object",
      "properties": {
        "quantity": {
          "type": "integer"
        },
        "amount_cents": {
          "type": "integer"
        },
        "events": {
          "type": "integer"
        }
      },
      "required": [
        "quantity",
        "amount_cents",
        "events"
      ],
      "description": "The non-negative rows only — the metered events themselves, charged and included alike. `charges.quantity === events` for a per-run meter."
    }
  }
}