UsageResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/tcgdata-dev/json-schema/tcgdata-dev-usage-response-schema.json",
  "title": "UsageResponse",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/tcgdata-dev-openapi.json#/components/schemas/UsageResponse",
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/$defs/Usage"
    },
    "upgrade": {
      "anyOf": [
        {
          "$ref": "#/$defs/UpgradeNotice"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "data",
    "upgrade"
  ],
  "$defs": {
    "UpgradeNotice": {
      "type": "object",
      "properties": {
        "activation": {
          "enum": [
            "payment",
            "manual"
          ],
          "description": "Published plans activate after Stripe confirms payment; custom access requires an agreement and manual activation."
        },
        "reason": {
          "enum": [
            "monthly_request_limit",
            "daily_request_limit",
            "rate_limited",
            "trial_expired"
          ]
        },
        "message": {
          "type": "string"
        },
        "current_plan": {
          "type": [
            "string",
            "null"
          ]
        },
        "recommended_plan": {
          "anyOf": [
            {
              "$ref": "#/$defs/UpgradePlan"
            },
            {
              "type": "null"
            }
          ]
        },
        "request_url": {
          "type": "string",
          "description": "Root-relative account plan-selection or custom-access contact path on https://tcgdata.dev. Opening it does not activate or charge for a plan."
        },
        "resets_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "activation",
        "reason",
        "message",
        "current_plan",
        "recommended_plan",
        "request_url",
        "resets_at"
      ],
      "description": "Upgrade suggestion for an authenticated account that reached a request limit or whose free test expired. Free tests recommend Starter and never renew; resets_at is their expiry, not a renewal. Paid accounts can wait for the applicable reset. recommended_plan is null when no suitable higher published plan is known. No automatic charge."
    },
    "UpgradePlan": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "monthly_eur": {
          "type": "number",
          "minimum": 0,
          "description": "Monthly EUR price excluding VAT. A proposal, not an automatic charge."
        },
        "currency": {
          "const": "EUR"
        },
        "monthly_requests": {
          "type": "integer",
          "minimum": 1
        },
        "daily_requests": {
          "type": "integer",
          "minimum": 1
        },
        "requests_per_minute": {
          "type": "integer",
          "minimum": 1
        },
        "batch_size": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200
        }
      },
      "required": [
        "id",
        "name",
        "monthly_eur",
        "currency",
        "monthly_requests",
        "daily_requests",
        "requests_per_minute",
        "batch_size"
      ]
    },
    "Usage": {
      "type": "object",
      "properties": {
        "credits": {
          "type": "integer",
          "minimum": 0,
          "deprecated": true,
          "description": "Historical successful-request telemetry. Not a quota and not equal to admitted requests; use requests and request_limit."
        },
        "reserved_credits": {
          "type": "integer",
          "minimum": 0,
          "deprecated": true,
          "description": "Deprecated in-flight telemetry retained for older clients. It does not reduce the request allowance."
        },
        "requests": {
          "type": "integer",
          "minimum": 0,
          "description": "Admitted HTTP requests in the billing period or fixed one-time free-test bucket, including this usage call and admitted errors."
        },
        "period": {
          "type": "string",
          "format": "date",
          "description": "First UTC date of the current billing period, or the free-test start date."
        },
        "day": {
          "type": "string",
          "format": "date",
          "description": "UTC date of the current daily request counter."
        },
        "billing_cycle": {
          "enum": [
            "calendar",
            "anniversary"
          ],
          "description": "Paid billing-cycle bookkeeping. Free tests keep one fixed bucket and never renew at these boundaries."
        },
        "billing_anchor_date": {
          "anyOf": [
            {
              "type": "string",
              "format": "date"
            },
            {
              "type": "null"
            }
          ]
        },
        "daily_requests": {
          "type": "integer",
          "minimum": 0
        },
        "daily_limit": {
          "type": "integer",
          "minimum": 0
        },
        "daily_remaining": {
          "type": "integer",
          "minimum": 0
        },
        "daily_resets_at": {
          "type": "string",
          "format": "date-time"
        },
        "batch_size": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200
        },
        "limit": {
          "type": "integer",
          "minimum": 0,
          "description": "Alias of request_limit: admitted HTTP requests allowed per billing period."
        },
        "remaining": {
          "type": "integer",
          "minimum": 0,
          "description": "Alias of requests_remaining, including this usage call."
        },
        "heavy_requests": {
          "type": "integer",
          "minimum": 0
        },
        "catalogue_requests": {
          "type": "integer",
          "minimum": 0
        },
        "history_requests": {
          "type": "integer",
          "minimum": 0
        },
        "image_requests": {
          "type": "integer",
          "minimum": 0
        },
        "response_bytes": {
          "type": "integer",
          "minimum": 0
        },
        "request_limit": {
          "type": "integer",
          "minimum": 0
        },
        "requests_remaining": {
          "type": "integer",
          "minimum": 0
        },
        "heavy_request_limit": {
          "type": "integer",
          "minimum": 0
        },
        "heavy_requests_remaining": {
          "type": "integer",
          "minimum": 0
        },
        "image_request_limit": {
          "type": "integer",
          "minimum": 0
        },
        "image_requests_remaining": {
          "type": "integer",
          "minimum": 0
        },
        "response_bytes_limit": {
          "type": "integer",
          "minimum": 0
        },
        "response_bytes_remaining": {
          "type": "integer",
          "minimum": 0
        },
        "resets_at": {
          "type": "string",
          "format": "date-time",
          "description": "Paid allowance reset, or free-test expiry. A free test never renews at this timestamp."
        }
      },
      "required": [
        "credits",
        "requests",
        "period",
        "billing_cycle",
        "billing_anchor_date",
        "daily_requests",
        "daily_limit",
        "daily_remaining",
        "daily_resets_at",
        "batch_size",
        "limit",
        "remaining",
        "resets_at",
        "heavy_requests",
        "catalogue_requests",
        "history_requests",
        "image_requests",
        "response_bytes",
        "request_limit",
        "requests_remaining",
        "heavy_request_limit",
        "heavy_requests_remaining",
        "image_request_limit",
        "image_requests_remaining",
        "response_bytes_limit",
        "response_bytes_remaining"
      ]
    }
  }
}