{
  "openapi": "3.1.0",
  "info": {
    "title": "Balance Query API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://query.cometapi.com"
    }
  ],
  "paths": {
    "/user/quota": {
      "get": {
        "summary": "Query account balance",
        "operationId": "getUserQuota",
        "description": "Retrieve account balance, cumulative usage, request count, and per-key quota details.",
        "parameters": [
          {
            "name": "key",
            "in": "query",
            "required": true,
            "description": "Your CometAPI API key.",
            "schema": {
              "type": "string",
              "example": "sk-xxx"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "username",
                    "total_quota",
                    "total_used_quota",
                    "request_count",
                    "keys"
                  ],
                  "properties": {
                    "username": {
                      "type": "string",
                      "description": "The account username."
                    },
                    "total_quota": {
                      "type": "number",
                      "description": "Current account balance in USD."
                    },
                    "total_used_quota": {
                      "type": "number",
                      "description": "Cumulative amount spent in USD."
                    },
                    "request_count": {
                      "type": "integer",
                      "description": "Total number of API requests made by this account."
                    },
                    "keys": {
                      "type": "array",
                      "description": "Per-key quota breakdown.",
                      "items": {
                        "type": "object",
                        "required": [
                          "name",
                          "remain_quota",
                          "used_quota"
                        ],
                        "properties": {
                          "name": {
                            "type": "string",
                            "description": "The display name of the API key."
                          },
                          "remain_quota": {
                            "type": "number",
                            "description": "Remaining quota for this key in USD. A value of `-1` indicates unlimited quota."
                          },
                          "used_quota": {
                            "type": "number",
                            "description": "Amount consumed by this key in USD. A value of `-1` indicates unlimited quota."
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "username": "example_user",
                  "total_quota": 2105.234088,
                  "total_used_quota": 21.065912,
                  "request_count": 1221,
                  "keys": [
                    {
                      "name": "my-key",
                      "remain_quota": 8.93872,
                      "used_quota": 2.099206
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}