CostAnalyticsQuery

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/vertesiahq/json-schema/vertesiahq-cost-analytics-query-schema.json",
  "title": "CostAnalyticsQuery",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/vertesiahq-costs-api-openapi.yml#/components/schemas/CostAnalyticsQuery",
  "type": "object",
  "properties": {
    "from": {
      "type": [
        "string",
        "number"
      ],
      "description": "Start time (ISO string or epoch ms)"
    },
    "to": {
      "type": [
        "string",
        "number"
      ],
      "description": "End time (ISO string or epoch ms)"
    },
    "group_by": {
      "type": "string",
      "enum": [
        "model",
        "environment",
        "account",
        "project",
        "project_tag",
        "provider",
        "service_tier",
        "interaction",
        "workflow",
        "agent_run",
        "workflow_run"
      ],
      "description": "Group results by this dimension. `agent_run` groups by root agent run, including the calls of its sub-agents; `workflow_run` groups by Temporal workflow run, which separates each sub-agent."
    },
    "resolution": {
      "type": "string",
      "enum": [
        "hour",
        "day",
        "week",
        "month"
      ],
      "description": "Time series resolution"
    },
    "model": {
      "type": "string",
      "description": "Filter by model pattern"
    },
    "environment_id": {
      "type": "string",
      "description": "Filter by environment ID"
    },
    "provider": {
      "type": "string",
      "description": "Filter by provider"
    },
    "service_tier": {
      "type": "string",
      "description": "Filter by resolved processing tier"
    },
    "project_id": {
      "type": "string",
      "description": "Filter by project ID (optional, for org scope)"
    },
    "workflow_id": {
      "type": "string",
      "description": "Filter by workflow / agent run ID"
    },
    "workflow_run_id": {
      "type": "string",
      "description": "Filter by Temporal workflow run ID"
    },
    "run_id": {
      "type": "string",
      "description": "Filter by interaction execution run ID"
    },
    "agent_run_id": {
      "type": "string",
      "description": "Filter by agent run ID"
    },
    "agent_only": {
      "type": "boolean",
      "description": "Restrict usage to agent runs and their attributed nested/background inference. Excludes standalone interactions and non-agent workflows. Defaults to false."
    },
    "interaction_id": {
      "type": "string",
      "description": "Filter by interaction id: stored ObjectId or namespaced in-code id"
    },
    "principal_id": {
      "type": "string",
      "description": "Filter by principal (bare user or API key id; matched against the suffix of principal_id)"
    },
    "account_id": {
      "type": "string",
      "description": "Filter by account ID (set automatically by server)"
    },
    "scope": {
      "type": "string",
      "enum": [
        "project",
        "org"
      ],
      "description": "Scope: 'project' (default, current project) or 'org' (all projects in account)"
    },
    "pricing_source": {
      "type": "string",
      "enum": [
        "list",
        "historical"
      ],
      "description": "Pricing source: 'list' (latest daily prices) or 'historical' (daily effective prices over the query range). Default: 'list'"
    },
    "no_cache": {
      "type": "boolean",
      "description": "Skip cache and force fresh query"
    }
  },
  "additionalProperties": false
}