usage_response

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/falpha-ai/json-schema/falpha-ai-usage-response-schema.json",
  "title": "usage_response",
  "x-generated": "2026-11-07",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/falpha-ai-openapi.json#/components/schemas/usage_response",
  "properties": {
    "window_days": {
      "type": "integer",
      "title": "Window Days",
      "description": "Size of the aggregation window in days"
    },
    "since": {
      "type": "string",
      "format": "date-time",
      "title": "Since",
      "description": "UTC start of the aggregation window"
    },
    "total": {
      "type": "integer",
      "title": "Total",
      "description": "Total successful requests recorded in the window"
    },
    "by_day": {
      "items": {
        "$ref": "#/$defs/usage_bucket"
      },
      "type": "array",
      "title": "By Day"
    },
    "by_endpoint": {
      "items": {
        "$ref": "#/$defs/usage_bucket"
      },
      "type": "array",
      "title": "By Endpoint"
    },
    "by_surface": {
      "items": {
        "$ref": "#/$defs/usage_bucket"
      },
      "type": "array",
      "title": "By Surface",
      "description": "Split by client surface: excel, sheets, sdk-python, zapier, or api (default)"
    },
    "by_client": {
      "items": {
        "$ref": "#/$defs/usage_bucket"
      },
      "type": "array",
      "title": "By Client",
      "description": "Split by anonymous install id (X-Falpha-Client header); requests without one bucket under '-'"
    },
    "meter": {
      "additionalProperties": true,
      "type": "object",
      "title": "Meter",
      "description": "Unified work meter summed over the window: db_calls, db_docs, db_ms (see dbmeter contract). Requests are traffic; the meter is work."
    }
  },
  "type": "object",
  "required": [
    "window_days",
    "since",
    "total",
    "by_day",
    "by_endpoint",
    "by_surface"
  ],
  "$defs": {
    "usage_bucket": {
      "properties": {
        "key": {
          "type": "string",
          "title": "Key",
          "description": "Bucket label: a YYYY-MM-DD day, an endpoint path, or a surface name"
        },
        "count": {
          "type": "integer",
          "title": "Count"
        }
      },
      "type": "object",
      "required": [
        "key",
        "count"
      ],
      "title": "usage_bucket"
    }
  }
}