schema/report.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "CUAR report schema version 2",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "status",
    "fetched_at",
    "timezone",
    "source",
    "usage",
    "banked_resets",
    "reset_observation",
    "limitations",
    "error"
  ],
  "properties": {
    "schema_version": {
      "const": 2
    },
    "status": {
      "enum": [
        "ok",
        "partial",
        "error"
      ]
    },
    "fetched_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "timezone": {
      "type": "string",
      "minLength": 1
    },
    "source": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "kind",
        "method"
      ],
      "properties": {
        "kind": {
          "const": "codex_app_server"
        },
        "method": {
          "const": "account/rateLimits/read"
        }
      }
    },
    "usage": {
      "anyOf": [
        {
          "$ref": "#/$defs/usage"
        },
        {
          "type": "null"
        }
      ]
    },
    "banked_resets": {
      "anyOf": [
        {
          "$ref": "#/$defs/banked_resets"
        },
        {
          "type": "null"
        }
      ]
    },
    "reset_observation": {
      "anyOf": [
        {
          "$ref": "#/$defs/reset_observation"
        },
        {
          "type": "null"
        }
      ]
    },
    "limitations": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/message"
      }
    },
    "error": {
      "anyOf": [
        {
          "$ref": "#/$defs/error"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "$defs": {
    "message": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1
        },
        "message": {
          "type": "string",
          "minLength": 1
        }
      }
    },
    "error": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "code",
        "stage",
        "retryable",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1
        },
        "stage": {
          "type": "string",
          "minLength": 1
        },
        "retryable": {
          "type": "boolean"
        },
        "message": {
          "type": "string",
          "minLength": 1
        }
      }
    },
    "usage": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "limit_id",
        "bucket_source",
        "window",
        "pace",
        "projection"
      ],
      "properties": {
        "limit_id": {
          "const": "codex"
        },
        "bucket_source": {
          "enum": [
            "rate_limits",
            "rate_limits_by_limit_id"
          ]
        },
        "window": {
          "$ref": "#/$defs/window"
        },
        "pace": {
          "$ref": "#/$defs/pace"
        },
        "projection": {
          "$ref": "#/$defs/projection"
        }
      }
    },
    "window": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "duration_seconds",
        "used_percent",
        "remaining_percent",
        "percentage_precision",
        "resets_at",
        "resets_at_local",
        "seconds_until_reset",
        "elapsed_seconds",
        "elapsed_percent"
      ],
      "properties": {
        "duration_seconds": {
          "const": 604800
        },
        "used_percent": {
          "type": "number",
          "minimum": 0,
          "maximum": 100
        },
        "remaining_percent": {
          "type": "number",
          "minimum": 0,
          "maximum": 100
        },
        "percentage_precision": {
          "$ref": "#/$defs/percentage_precision"
        },
        "resets_at": {
          "type": "string",
          "format": "date-time"
        },
        "resets_at_local": {
          "type": "string"
        },
        "seconds_until_reset": {
          "type": "integer",
          "minimum": 0
        },
        "elapsed_seconds": {
          "type": "integer",
          "minimum": 0,
          "maximum": 604800
        },
        "elapsed_percent": {
          "type": "number",
          "minimum": 0,
          "maximum": 100
        }
      }
    },
    "percentage_precision": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "source_granularity_percentage_points",
        "remaining_percent_interpretation",
        "remaining_capacity_state"
      ],
      "properties": {
        "source_granularity_percentage_points": {
          "const": 1
        },
        "remaining_percent_interpretation": {
          "const": "upper_bound"
        },
        "remaining_capacity_state": {
          "enum": [
            "reported_upper_bound",
            "less_than_one_percent",
            "exhausted"
          ]
        }
      }
    },
    "pace": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "delta_percentage_points",
        "relation",
        "neutral_threshold_percentage_points"
      ],
      "properties": {
        "delta_percentage_points": {
          "type": "number"
        },
        "relation": {
          "enum": [
            "above",
            "approximately_linear",
            "below"
          ]
        },
        "neutral_threshold_percentage_points": {
          "const": 5
        }
      }
    },
    "projection": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "end_state",
        "end_percent",
        "exhaustion_state",
        "exhaustion_at",
        "exhaustion_at_local"
      ],
      "properties": {
        "end_state": {
          "enum": [
            "projected",
            "insufficient_elapsed"
          ]
        },
        "end_percent": {
          "type": [
            "number",
            "null"
          ]
        },
        "exhaustion_state": {
          "enum": [
            "before_reset",
            "not_before_reset",
            "already_exhausted",
            "zero_usage",
            "insufficient_elapsed"
          ]
        },
        "exhaustion_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "exhaustion_at_local": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "banked_resets": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "available_count",
        "detail_state",
        "listed_available_count",
        "unlisted_available_count",
        "credits"
      ],
      "properties": {
        "available_count": {
          "type": "integer",
          "minimum": 0
        },
        "detail_state": {
          "enum": [
            "complete",
            "partial",
            "count_only"
          ]
        },
        "listed_available_count": {
          "type": "integer",
          "minimum": 0
        },
        "unlisted_available_count": {
          "type": "integer",
          "minimum": 0
        },
        "credits": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/credit"
          }
        }
      }
    },
    "credit": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "reset_type",
        "expires_at",
        "expires_at_local",
        "expiry_state",
        "seconds_until_expiry"
      ],
      "properties": {
        "reset_type": {
          "enum": [
            "codex_rate_limits",
            "unknown"
          ]
        },
        "expires_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "expires_at_local": {
          "type": [
            "string",
            "null"
          ]
        },
        "expiry_state": {
          "enum": [
            "future",
            "expired",
            "no_expiration_reported"
          ]
        },
        "seconds_until_expiry": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0
        }
      }
    },
    "reset_observation": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "ledger_status",
        "state",
        "detected_now",
        "latest_event"
      ],
      "properties": {
        "ledger_status": {
          "enum": [
            "active",
            "disabled_test_mode",
            "unavailable"
          ]
        },
        "state": {
          "enum": [
            "no_prior_observation",
            "no_evidence",
            "unexpected_usage_reset_observed",
            "unavailable"
          ]
        },
        "detected_now": {
          "type": "boolean"
        },
        "latest_event": {
          "anyOf": [
            {
              "$ref": "#/$defs/reset_event"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    "reset_event": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "observed_at",
        "observed_at_local",
        "previous_observed_at",
        "previous_observed_at_local",
        "prior_scheduled_reset_at",
        "prior_scheduled_reset_at_local",
        "minutes_before_prior_scheduled_reset",
        "classification"
      ],
      "properties": {
        "observed_at": {
          "type": "string",
          "format": "date-time"
        },
        "observed_at_local": {
          "type": "string",
          "minLength": 1
        },
        "previous_observed_at": {
          "type": "string",
          "format": "date-time"
        },
        "previous_observed_at_local": {
          "type": "string",
          "minLength": 1
        },
        "prior_scheduled_reset_at": {
          "type": "string",
          "format": "date-time"
        },
        "prior_scheduled_reset_at_local": {
          "type": "string",
          "minLength": 1
        },
        "minutes_before_prior_scheduled_reset": {
          "type": "integer",
          "minimum": 0
        },
        "classification": {
          "enum": [
            "likely_unscheduled",
            "banked_reset_possible"
          ]
        }
      }
    }
  }
}