{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hubris-pw/json-schema/hubris-pw-usage-response-schema.json",
  "title": "UsageResponse",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hubris-pw-openapi.json#/components/schemas/UsageResponse",
  "type": "object",
  "properties": {
    "object": {
      "type": "string",
      "enum": [
        "usage"
      ]
    },
    "period": {
      "type": "object",
      "properties": {
        "from": {
          "type": "string",
          "format": "date-time",
          "description": "Начало периода (UTC, ISO 8601). Включительно."
        },
        "to": {
          "type": "string",
          "format": "date-time",
          "description": "Конец периода (UTC, ISO 8601). Включительно."
        },
        "shortcut": {
          "$ref": "#/$defs/UsagePeriod"
        }
      },
      "required": [
        "from",
        "to",
        "shortcut"
      ]
    },
    "scope": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "key_id": {
              "type": "string",
              "format": "uuid"
            },
            "key_prefix": {
              "type": "string"
            }
          },
          "required": [
            "key_id",
            "key_prefix"
          ]
        },
        {
          "type": "object",
          "properties": {
            "account": {
              "type": "boolean",
              "enum": [
                true
              ]
            },
            "key_id": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid"
            }
          },
          "required": [
            "account",
            "key_id"
          ]
        }
      ],
      "description": "Обычный ключ: расход только по нему. OAuth-токен: расход всего подключения приложения, `key_id` — текущий токен. Management-ключ: весь аккаунт (`account: true`), опционально суженный параметром `key_id`."
    },
    "totals": {
      "type": "object",
      "properties": {
        "requests": {
          "type": "integer",
          "minimum": 0
        },
        "prompt_tokens": {
          "type": "integer",
          "minimum": 0,
          "description": "Новые токены входа, без кеша."
        },
        "completion_tokens": {
          "type": "integer",
          "minimum": 0
        },
        "input_tokens_total": {
          "type": "integer",
          "minimum": 0,
          "description": "Весь вход: prompt_tokens + cache_read_tokens + cache_write_tokens."
        },
        "total_tokens": {
          "type": "integer",
          "minimum": 0,
          "description": "Все токены периода: input_tokens_total + completion_tokens."
        },
        "cost_rub": {
          "type": "number",
          "description": "Итоговая стоимость за период в рублях. Эквивалент cost_kopecks/100."
        },
        "cost_kopecks": {
          "type": "string",
          "description": "Итоговая стоимость в копейках (строка для точности при сериализации bigint)."
        },
        "cache_read_tokens": {
          "type": "integer"
        },
        "cache_write_tokens": {
          "type": "integer"
        },
        "reasoning_tokens": {
          "type": "integer"
        },
        "cache_hit_rate": {
          "type": "number"
        },
        "cache_savings_kopecks": {
          "type": "string"
        },
        "cache_savings_rub": {
          "type": "number"
        }
      },
      "required": [
        "requests",
        "prompt_tokens",
        "completion_tokens",
        "input_tokens_total",
        "total_tokens",
        "cost_rub",
        "cost_kopecks",
        "cache_read_tokens",
        "cache_write_tokens",
        "reasoning_tokens",
        "cache_hit_rate",
        "cache_savings_kopecks",
        "cache_savings_rub"
      ]
    },
    "granularity": {
      "$ref": "#/$defs/UsageGranularity"
    },
    "buckets": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/UsageBucket"
      },
      "description": "Точки графика. Null, если `granularity` не запрошен."
    },
    "by_key": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object",
        "properties": {
          "key_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "key_prefix": {
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "requests": {
            "type": "integer",
            "minimum": 0
          },
          "total_tokens": {
            "type": "integer",
            "minimum": 0,
            "description": "Весь вход с кешем + выход."
          },
          "cost_kopecks": {
            "type": "string",
            "description": "Копейки строкой — как в totals."
          }
        },
        "required": [
          "key_id",
          "key_prefix",
          "name",
          "requests",
          "total_tokens",
          "cost_kopecks"
        ]
      },
      "description": "Разбивка по ключам аккаунта (`group_by=key`, только management-ключом). Иначе отсутствует."
    },
    "by_model": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string"
          },
          "requests": {
            "type": "integer",
            "minimum": 0
          },
          "prompt_tokens": {
            "type": "integer",
            "minimum": 0,
            "description": "Новые токены входа, без кеша."
          },
          "completion_tokens": {
            "type": "integer",
            "minimum": 0
          },
          "cache_read_tokens": {
            "type": "integer",
            "minimum": 0
          },
          "cache_write_tokens": {
            "type": "integer",
            "minimum": 0
          },
          "input_tokens_total": {
            "type": "integer",
            "minimum": 0,
            "description": "Весь вход с кешем."
          },
          "total_tokens": {
            "type": "integer",
            "minimum": 0,
            "description": "input_tokens_total + completion_tokens."
          },
          "cost_kopecks": {
            "type": "string",
            "description": "Копейки строкой — как в totals."
          }
        },
        "required": [
          "model",
          "requests",
          "prompt_tokens",
          "completion_tokens",
          "cache_read_tokens",
          "cache_write_tokens",
          "input_tokens_total",
          "total_tokens",
          "cost_kopecks"
        ]
      },
      "description": "Разбивка по моделям (`group_by=model`, только management-ключом). Иначе отсутствует."
    }
  },
  "required": [
    "object",
    "period",
    "scope",
    "totals",
    "granularity",
    "buckets"
  ],
  "$defs": {
    "UsageBucket": {
      "type": "object",
      "properties": {
        "bucket": {
          "type": "string",
          "format": "date-time",
          "description": "Начало интервала в ISO 8601 (UTC)."
        },
        "cost_rub": {
          "type": "number",
          "description": "Стоимость за интервал в рублях. cost_kopecks/100."
        },
        "cost_kopecks": {
          "type": "string",
          "description": "Стоимость за интервал в копейках (строка — чтобы пережить JSON без потери точности)."
        },
        "requests": {
          "type": "integer",
          "minimum": 0
        }
      },
      "required": [
        "bucket",
        "cost_rub",
        "cost_kopecks",
        "requests"
      ]
    },
    "UsageGranularity": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "hour",
        "day"
      ],
      "description": "Если `granularity` был задан, тут он же. Иначе null."
    },
    "UsagePeriod": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "today",
        "24h",
        "7d",
        "30d",
        "mtd"
      ],
      "description": "Шорткат, если запрос был сделан через `?period=`. Иначе null."
    }
  }
}