CostAnalyticsResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/vertesiahq/json-schema/vertesiahq-cost-analytics-response-schema.json",
  "title": "CostAnalyticsResponse",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/vertesiahq-costs-api-openapi.yml#/components/schemas/CostAnalyticsResponse",
  "type": "object",
  "properties": {
    "summary": {
      "$ref": "#/$defs/CostSummary"
    },
    "by_dimension": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/CostByDimension"
      }
    },
    "time_series": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/CostTimeSeriesPoint"
      }
    },
    "pricing": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ModelPricing"
      }
    },
    "pricing_coverage": {
      "type": "object",
      "properties": {
        "priced_calls": {
          "type": "number"
        },
        "unpriced_calls": {
          "type": "number"
        },
        "assumed_default_calls": {
          "type": "number"
        },
        "unpriced": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "model": {
                "type": "string"
              },
              "provider": {
                "type": "string"
              },
              "service_tier": {
                "type": "string"
              },
              "calls": {
                "type": "number"
              }
            },
            "required": [
              "model",
              "service_tier",
              "calls"
            ],
            "additionalProperties": false
          }
        },
        "cost_by_source": {
          "type": "object",
          "properties": {
            "provider_billed": {
              "type": "number",
              "description": "USD the provider reported billing for the calls."
            },
            "run_time_estimate": {
              "type": "number",
              "description": "USD estimated from list prices when the calls ran, for calls with no billed amount."
            },
            "price_table": {
              "type": "number",
              "description": "USD computed from the pricing table, for calls with no cost recorded when they ran."
            }
          },
          "required": [
            "provider_billed",
            "run_time_estimate",
            "price_table"
          ],
          "additionalProperties": false,
          "description": "How the total cost splits by where each call's cost came from."
        }
      },
      "required": [
        "priced_calls",
        "unpriced_calls",
        "assumed_default_calls",
        "unpriced"
      ],
      "additionalProperties": false
    },
    "query_range": {
      "type": "object",
      "properties": {
        "from": {
          "type": "string"
        },
        "to": {
          "type": "string"
        }
      },
      "required": [
        "from",
        "to"
      ],
      "additionalProperties": false
    },
    "cached": {
      "type": "boolean"
    }
  },
  "required": [
    "summary",
    "by_dimension",
    "time_series",
    "pricing",
    "query_range",
    "cached"
  ],
  "additionalProperties": false,
  "$defs": {
    "CostByDimension": {
      "type": "object",
      "properties": {
        "dimension": {
          "type": "string"
        },
        "label": {
          "type": "string"
        },
        "provider": {
          "type": "string"
        },
        "service_tier": {
          "type": "string"
        },
        "cost": {
          "type": "number"
        },
        "input_tokens": {
          "type": "number"
        },
        "cached_input_tokens": {
          "type": "number"
        },
        "cache_write_input_tokens": {
          "type": "number"
        },
        "output_tokens": {
          "type": "number"
        },
        "calls": {
          "type": "number"
        },
        "periods": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/CostTimeSeriesPoint"
          }
        }
      },
      "required": [
        "dimension",
        "cost",
        "input_tokens",
        "output_tokens",
        "calls"
      ],
      "additionalProperties": false
    },
    "CostSummary": {
      "type": "object",
      "properties": {
        "total_cost": {
          "type": "number"
        },
        "total_input_tokens": {
          "type": "number"
        },
        "total_cached_input_tokens": {
          "type": "number"
        },
        "total_cache_write_input_tokens": {
          "type": "number"
        },
        "total_output_tokens": {
          "type": "number"
        },
        "total_calls": {
          "type": "number"
        },
        "total_duration_ms": {
          "type": "number"
        }
      },
      "required": [
        "total_cost",
        "total_input_tokens",
        "total_output_tokens",
        "total_calls",
        "total_duration_ms"
      ],
      "additionalProperties": false
    },
    "CostTimeSeriesPoint": {
      "type": "object",
      "properties": {
        "timestamp": {
          "type": "string"
        },
        "cost": {
          "type": "number"
        },
        "input_tokens": {
          "type": "number"
        },
        "cached_input_tokens": {
          "type": "number"
        },
        "cache_write_input_tokens": {
          "type": "number"
        },
        "output_tokens": {
          "type": "number"
        },
        "calls": {
          "type": "number"
        }
      },
      "required": [
        "timestamp",
        "cost",
        "input_tokens",
        "output_tokens",
        "calls"
      ],
      "additionalProperties": false
    },
    "ModelPricing": {
      "type": "object",
      "properties": {
        "model": {
          "type": "string"
        },
        "provider": {
          "type": "string"
        },
        "provider_account_id": {
          "type": "string"
        },
        "service_tier": {
          "type": "string",
          "description": "Processing tier this price applies to"
        },
        "min_prompt_tokens": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991,
          "description": "When set, these prices apply to calls whose prompt (input, cached and cache-write tokens) is longer than this many tokens, in place of the prices without it."
        },
        "input_price_per_m_tokens": {
          "type": "number"
        },
        "cached_input_price_per_m_tokens": {
          "type": "number"
        },
        "cache_write_input_price_per_m_tokens": {
          "type": "number"
        },
        "output_price_per_m_tokens": {
          "type": "number"
        },
        "source": {
          "type": "string",
          "enum": [
            "billing_export",
            "model_pricing_daily",
            "run_time_estimate",
            "unavailable"
          ],
          "description": "Where the rates come from. `run_time_estimate` rates are the ones recorded on the calls when their cost was estimated; the others come from the pricing catalog."
        }
      },
      "required": [
        "model",
        "input_price_per_m_tokens",
        "output_price_per_m_tokens",
        "source"
      ],
      "additionalProperties": false
    }
  }
}