{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/immersivecommons-com/json-schema/immersivecommons-com-admin-llm-usage-response-schema.json",
  "title": "AdminLlmUsageResponse",
  "description": "Month-to-date IC Key usage read straight off the gateway's meters. Every figure is fail-soft: an unreadable counter reads as 0, never as an error.",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/immersivecommons-com-openapi.json#/components/schemas/AdminLlmUsageResponse",
  "type": "object",
  "required": [
    "ok",
    "month",
    "week_of",
    "generated_at",
    "providers",
    "models",
    "keys",
    "events"
  ],
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "month": {
      "type": "string",
      "description": "YYYY-MM (UTC) the month-to-date figures cover."
    },
    "week_of": {
      "type": "string",
      "description": "Monday date (YYYY-MM-DD) the per-key weekly_used figures cover."
    },
    "generated_at": {
      "type": "string"
    },
    "providers": {
      "type": "object",
      "required": [
        "nebius",
        "zai"
      ],
      "properties": {
        "nebius": {
          "$ref": "#/$defs/LlmProviderMonthUsage"
        },
        "zai": {
          "$ref": "#/$defs/LlmProviderMonthUsage"
        }
      }
    },
    "models": {
      "type": "array",
      "description": "Per-model month-to-date, cost desc then tokens desc; rows with no traffic are omitted.",
      "items": {
        "type": "object",
        "required": [
          "model",
          "provider",
          "tokens_in",
          "tokens_out",
          "cost_usd",
          "requests"
        ],
        "properties": {
          "model": {
            "type": "string"
          },
          "provider": {
            "type": "string"
          },
          "tokens_in": {
            "type": "integer"
          },
          "tokens_out": {
            "type": "integer"
          },
          "cost_usd": {
            "type": "number"
          },
          "requests": {
            "type": "integer"
          }
        }
      }
    },
    "keys": {
      "type": "array",
      "description": "One row per live proxy key the audit ring can see (never a plaintext). Month cost desc.",
      "items": {
        "type": "object",
        "required": [
          "prefix",
          "kind",
          "requester_name",
          "weekly_used",
          "weekly_cap",
          "month_cost_usd",
          "models"
        ],
        "properties": {
          "prefix": {
            "type": "string",
            "description": "Display prefix of the minted key."
          },
          "kind": {
            "type": "string",
            "enum": [
              "workshop",
              "member",
              "benchmark"
            ]
          },
          "requester_name": {
            "type": "string"
          },
          "weekly_used": {
            "type": "integer",
            "description": "This week's tokens (informational on a usd_budget key)."
          },
          "weekly_cap": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Legacy weekly-token keys only; null otherwise."
          },
          "month_cost_usd": {
            "type": "number"
          },
          "budget_usd": {
            "type": [
              "number",
              "null"
            ],
            "description": "The key's USD budget; null on a legacy key without one."
          },
          "budget_period": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "month",
              "lifetime",
              null
            ]
          },
          "budget_used_usd": {
            "type": "number",
            "description": "Spent against the budget: month cost, or lifetime total for a lifetime budget."
          },
          "models": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Every model id this key has used."
          },
          "default_model": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    },
    "keys_audit_window": {
      "type": "integer",
      "description": "How many audit entries the key enumeration could see; keys whose approval rolled off the ring are not listed."
    },
    "events": {
      "type": "array",
      "description": "The last 50 gateway events, newest first.",
      "items": {
        "type": "object",
        "properties": {
          "ts": {
            "type": "string"
          },
          "sha12": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "provider": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "api": {
            "type": "string"
          },
          "in": {
            "type": "integer"
          },
          "out": {
            "type": "integer"
          },
          "cost_uusd": {
            "type": "integer",
            "description": "micro-USD"
          },
          "status": {
            "type": "integer"
          },
          "ms": {
            "type": "integer"
          }
        }
      }
    }
  },
  "$defs": {
    "LlmProviderMonthUsage": {
      "type": "object",
      "required": [
        "tokens_in",
        "tokens_out",
        "cost_usd",
        "requests",
        "cap_usd",
        "cap_pct"
      ],
      "properties": {
        "tokens_in": {
          "type": "integer"
        },
        "tokens_out": {
          "type": "integer"
        },
        "cost_usd": {
          "type": "number",
          "description": "USD IC paid this month (UTC). 0 for a flat-plan provider."
        },
        "requests": {
          "type": "integer"
        },
        "cap_usd": {
          "type": [
            "number",
            "null"
          ],
          "description": "The gateway's monthly USD cap for this provider; null when the provider has none."
        },
        "cap_pct": {
          "type": [
            "number",
            "null"
          ],
          "description": "cost_usd / cap_usd as a percentage, one decimal; null without a cap."
        }
      }
    }
  }
}