HTTP models: ToolEffect – UsageSessionAggregateBreakdown
Exact OpenAPI component declarations. $ref values identify other components in the complete schema.
ToolEffect
Section titled “ToolEffect”{ "type": "string", "enum": [ "none", "idempotent", "external" ], "title": "ToolEffect", "description": "Declared side-effect semantics for a tool execution.\n\nClassify what replay can do to externally meaningful durable state. ``NONE``\ndoes not mutate it, ``IDEMPOTENT`` may mutate it but a stable downstream\nidentity or equivalent contract collapses replay, and ``EXTERNAL`` has a\nnon-idempotent or outcome-ambiguous durable mutation. Transport, billing,\nobservability, and names such as \"read\" do not determine the value.\n\nThe runtime uses this as execution metadata, not as an authorization\ndecision: policy still decides whether a call may run. Run\n``cayu guide tool-effects`` for the canonical decision table."}ToolResultPart
Section titled “ToolResultPart”{ "properties": { "type": { "type": "string", "const": "tool_result", "title": "Type", "default": "tool_result" }, "tool_call_id": { "type": "string", "title": "Tool Call Id" }, "tool_name": { "type": "string", "title": "Tool Name" }, "content": { "type": "string", "title": "Content", "default": "" }, "structured": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Structured" }, "artifacts": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Artifacts" }, "is_error": { "type": "boolean", "title": "Is Error", "default": false }, "tool_round_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tool Round Id" }, "model_step_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Step Id" }, "model_attempt_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Attempt Id" } }, "additionalProperties": false, "type": "object", "required": [ "tool_call_id", "tool_name" ], "title": "ToolResultPart"}ToolRoundRecoveryBody
Section titled “ToolRoundRecoveryBody”{ "properties": { "session_id": { "type": "string", "minLength": 1, "title": "Session Id" }, "task_worker_id": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "title": "Task Worker Id" }, "task_handoff_id": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "title": "Task Handoff Id" }, "round_id": { "type": "string", "minLength": 1, "title": "Round Id" }, "tool_call_id": { "type": "string", "minLength": 1, "title": "Tool Call Id" }, "outcome": { "$ref": "#/components/schemas/ToolApprovalRecoveryOutcome" }, "message": { "type": "string", "minLength": 1, "title": "Message" }, "structured": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Structured" }, "artifacts": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Artifacts" }, "reason": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "title": "Reason" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" }, "resolved_by": { "anyOf": [ { "$ref": "#/components/schemas/ResolutionActor" }, { "type": "null" } ] }, "max_steps": { "anyOf": [ { "type": "integer", "maximum": 9007199254740991.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Max Steps" }, "limits": { "anyOf": [ { "$ref": "#/components/schemas/RunLimits" }, { "type": "null" } ] }, "budget_limits": { "anyOf": [ { "items": { "$ref": "#/components/schemas/BudgetLimit" }, "type": "array" }, { "type": "null" } ], "title": "Budget Limits" }, "retry_policy": { "anyOf": [ { "$ref": "#/components/schemas/RetryPolicy" }, { "type": "null" } ] }, "structured_output": { "anyOf": [ { "$ref": "#/components/schemas/StructuredOutputSpec" }, { "type": "null" } ] }, "thinking": { "anyOf": [ { "$ref": "#/components/schemas/ThinkingConfig" }, { "type": "null" } ] } }, "type": "object", "required": [ "session_id", "round_id", "tool_call_id", "outcome", "message" ], "title": "ToolRoundRecoveryBody", "description": "Body for recovering a crashed ordinary tool call with an operator outcome.\n\n``max_steps``, ``limits``, ``budget_limits``, and ``retry_policy`` default\nto ``None``, which restores the configuration persisted with the pending\ntool round. An explicit value is accepted only when it preserves the\ninvocation's frozen execution profile."}TranscriptSummary
Section titled “TranscriptSummary”{ "properties": { "total_messages": { "type": "integer", "minimum": 0.0, "title": "Total Messages" } }, "additionalProperties": false, "type": "object", "required": [ "total_messages" ], "title": "TranscriptSummary"}UpdateSessionLabelsBody
Section titled “UpdateSessionLabelsBody”{ "properties": { "labels": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Labels" } }, "additionalProperties": false, "type": "object", "required": [ "labels" ], "title": "UpdateSessionLabelsBody"}UpdateSessionMetadataBody
Section titled “UpdateSessionMetadataBody”{ "properties": { "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata", "description": "Complete replacement for user-authored session metadata. Cayu-owned entries are preserved by the store and must not be supplied." } }, "additionalProperties": false, "type": "object", "required": [ "metadata" ], "title": "UpdateSessionMetadataBody"}UsageAggregateBreakdown
Section titled “UsageAggregateBreakdown”{ "properties": { "groups": { "items": { "$ref": "#/components/schemas/UsageAggregateGroup" }, "type": "array", "maxItems": 100, "title": "Groups" }, "remainder": { "anyOf": [ { "$ref": "#/components/schemas/UsageAggregateRemainder" }, { "type": "null" } ] }, "accuracy": { "$ref": "#/components/schemas/AggregateAccuracy" } }, "additionalProperties": false, "type": "object", "required": [ "groups", "remainder", "accuracy" ], "title": "UsageAggregateBreakdown", "description": "Deterministic top groups plus an exact remainder when detail is bounded."}UsageAggregateGroup
Section titled “UsageAggregateGroup”{ "properties": { "provider_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Name" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "totals": { "$ref": "#/components/schemas/UsageAggregateTotals" } }, "additionalProperties": false, "type": "object", "required": [ "provider_name", "model", "totals" ], "title": "UsageAggregateGroup", "description": "One provider/model grouping inside a bounded usage breakdown."}UsageAggregateRemainder
Section titled “UsageAggregateRemainder”{ "properties": { "group_count": { "type": "string", "pattern": "^[1-9]\\d*$", "title": "Group Count" }, "totals": { "$ref": "#/components/schemas/UsageAggregateTotals" } }, "additionalProperties": false, "type": "object", "required": [ "group_count", "totals" ], "title": "UsageAggregateRemainder", "description": "Exact totals represented by groups omitted from a bounded breakdown."}UsageAggregateTotals
Section titled “UsageAggregateTotals”{ "properties": { "session_count": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Session Count" }, "model_steps": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Model Steps" }, "model_steps_with_usage": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Model Steps With Usage" }, "tool_calls": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Tool Calls" }, "usage": { "$ref": "#/components/schemas/AggregateUsageMetrics" } }, "additionalProperties": false, "type": "object", "required": [ "session_count", "model_steps", "model_steps_with_usage", "tool_calls", "usage" ], "title": "UsageAggregateTotals", "description": "Identity-free activity and token totals for one aggregate scope."}UsageBillingCostBreakdown
Section titled “UsageBillingCostBreakdown”{ "properties": { "identified_model_steps": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Identified Model Steps" }, "identified_auxiliary_attempts": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Identified Auxiliary Attempts", "default": "0" }, "groups": { "items": { "$ref": "#/components/schemas/UsageBillingCostGroup" }, "type": "array", "maxItems": 100, "title": "Groups" }, "remainder": { "anyOf": [ { "$ref": "#/components/schemas/UsageBillingCostRemainder" }, { "type": "null" } ] }, "accuracy": { "$ref": "#/components/schemas/AggregateAccuracy" } }, "additionalProperties": false, "type": "object", "required": [ "identified_model_steps", "groups", "remainder", "accuracy" ], "title": "UsageBillingCostBreakdown", "description": "Bounded identity detail for evaluated cost inputs, with an exact remainder."}UsageBillingCostGroup
Section titled “UsageBillingCostGroup”{ "properties": { "billing_identity": { "$ref": "#/components/schemas/UsageBillingIdentity" }, "pricing_provider_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pricing Provider Name" }, "pricing_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pricing Model" }, "priced": { "type": "boolean", "title": "Priced" }, "model_steps": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Model Steps" }, "auxiliary_attempts": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Auxiliary Attempts", "default": "0" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Currency" }, "total_cost": { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Total Cost" }, "missing_pricing_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Missing Pricing Reason" } }, "additionalProperties": false, "type": "object", "required": [ "billing_identity", "priced", "model_steps", "total_cost" ], "title": "UsageBillingCostGroup", "description": "One bounded, identity-bearing group of equivalent pricing outcomes."}UsageBillingCostRemainder
Section titled “UsageBillingCostRemainder”{ "properties": { "group_count": { "type": "string", "pattern": "^[1-9]\\d*$", "title": "Group Count" }, "model_steps": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Model Steps" }, "auxiliary_attempts": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Auxiliary Attempts", "default": "0" }, "priced_auxiliary_attempts": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Priced Auxiliary Attempts", "default": "0" }, "unpriced_auxiliary_attempts": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Unpriced Auxiliary Attempts", "default": "0" }, "priced_model_steps": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Priced Model Steps" }, "unpriced_model_steps": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Unpriced Model Steps" } }, "additionalProperties": false, "type": "object", "required": [ "group_count", "model_steps", "priced_model_steps", "unpriced_model_steps" ], "title": "UsageBillingCostRemainder", "description": "Exact counts for identity-bearing pricing groups omitted from bounded detail."}UsageBillingIdentity
Section titled “UsageBillingIdentity”{ "properties": { "provider_name": { "type": "string", "title": "Provider Name" }, "resource_id": { "type": "string", "title": "Resource Id" }, "request_evidence": { "additionalProperties": { "type": "string" }, "type": "object", "maxProperties": 4, "title": "Request Evidence" }, "completion_evidence": { "additionalProperties": { "type": "string" }, "type": "object", "maxProperties": 1, "title": "Completion Evidence" } }, "additionalProperties": false, "type": "object", "required": [ "provider_name", "resource_id" ], "title": "UsageBillingIdentity", "description": "Bounded commercial identity safe to return in an aggregate response."}UsageBreakdownItem
Section titled “UsageBreakdownItem”{ "properties": { "provider_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Name" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model" }, "session_count": { "type": "integer", "minimum": 0.0, "title": "Session Count" }, "model_steps": { "type": "integer", "minimum": 0.0, "title": "Model Steps" }, "usage": { "$ref": "#/components/schemas/AggregateUsageMetrics" } }, "additionalProperties": false, "type": "object", "required": [ "provider_name", "model", "session_count", "model_steps", "usage" ], "title": "UsageBreakdownItem"}UsageCostRollup
Section titled “UsageCostRollup”{ "properties": { "price_book_version": { "type": "string", "title": "Price Book Version" }, "price_book_generated_at": { "type": "string", "title": "Price Book Generated At" }, "accuracy": { "$ref": "#/components/schemas/AggregateAccuracy" }, "evaluated_model_steps": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Evaluated Model Steps" }, "evaluated_auxiliary_attempts": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Evaluated Auxiliary Attempts", "default": "0" }, "priced_auxiliary_attempts": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Priced Auxiliary Attempts", "default": "0" }, "unpriced_auxiliary_attempts": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Unpriced Auxiliary Attempts", "default": "0" }, "priced_model_steps": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Priced Model Steps" }, "unpriced_model_steps": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Unpriced Model Steps" }, "unevaluated_model_steps": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Unevaluated Model Steps" }, "currencies": { "items": { "$ref": "#/components/schemas/UsageCurrencyCost" }, "type": "array", "maxItems": 5000, "title": "Currencies" }, "unpriced_reasons": { "items": { "$ref": "#/components/schemas/UsageUnpricedReason" }, "type": "array", "maxItems": 5000, "title": "Unpriced Reasons" }, "billing_breakdown": { "$ref": "#/components/schemas/UsageBillingCostBreakdown" } }, "additionalProperties": false, "type": "object", "required": [ "price_book_version", "price_book_generated_at", "accuracy", "evaluated_model_steps", "priced_model_steps", "unpriced_model_steps", "unevaluated_model_steps", "currencies", "unpriced_reasons", "billing_breakdown" ], "title": "UsageCostRollup", "description": "Bounded cost result derived from grouped price-relevant inputs."}UsageCurrencyCost
Section titled “UsageCurrencyCost”{ "properties": { "currency": { "type": "string", "title": "Currency" }, "model_steps": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Model Steps" }, "auxiliary_attempts": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Auxiliary Attempts", "default": "0" }, "hosted_resources": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Hosted Resources", "default": "0" }, "total_cost": { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Total Cost" } }, "additionalProperties": false, "type": "object", "required": [ "currency", "model_steps", "total_cost" ], "title": "UsageCurrencyCost", "description": "Exact estimated model-step and hosted-resource cost for one currency."}UsageRollupRequest
Section titled “UsageRollupRequest”{ "properties": { "start_at": { "type": "string", "format": "date-time", "title": "Start At" }, "end_at": { "type": "string", "format": "date-time", "title": "End At" }, "session_filter": { "$ref": "#/components/schemas/SessionAggregateFilter" }, "group_limit": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "Group Limit", "description": "Maximum returned groups, applied independently to provider, model, and billing identity breakdowns. Omitted groups are represented by an explicit remainder.", "default": 20 }, "session_group_limit": { "anyOf": [ { "type": "integer", "maximum": 100.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Session Group Limit", "description": "Opt-in maximum number of per-session usage groups. Omitted matching sessions are represented by an exact aggregate remainder. When omitted, stores perform no per-session breakdown or session-aware pricing work." }, "pricing_input_limit": { "type": "integer", "maximum": 5000.0, "minimum": 1.0, "title": "Pricing Input Limit", "description": "Maximum canonical price-input groups, applied independently to the shared projection and, when session_group_limit is present, the session-aware projection.", "default": 1000 }, "pricing": { "anyOf": [ { "$ref": "#/components/schemas/PriceBook" }, { "type": "null" } ], "description": "Optional bounded price book. The serialized value may contain at most 2 MiB, 500 prices, 2,000 price match rules, 1,000 resource mappings, 100 contextual requirements, and 2,000 contextual selector values. Each currency identity may contain at most 64 UTF-8 bytes. The price-input limit multiplied by the resolution candidates may not exceed 500,000." } }, "additionalProperties": false, "type": "object", "required": [ "start_at", "end_at" ], "title": "UsageRollupRequest"}UsageRollupResponse
Section titled “UsageRollupResponse”{ "properties": { "reported_costs": { "anyOf": [ { "$ref": "#/components/schemas/ReportedCostPage" }, { "type": "null" } ] }, "scope": { "type": "string", "const": "configured_session_store", "title": "Scope" }, "time_basis": { "type": "string", "const": "event.timestamp", "title": "Time Basis" }, "session_filter_basis": { "type": "string", "const": "current_session_attributes", "title": "Session Filter Basis" }, "as_of": { "type": "string", "format": "date-time", "title": "As Of" }, "start_at": { "type": "string", "format": "date-time", "title": "Start At" }, "end_at": { "type": "string", "format": "date-time", "title": "End At" }, "accuracy": { "$ref": "#/components/schemas/AggregateAccuracy" }, "matching_session_count": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Matching Session Count" }, "active_session_count": { "type": "string", "pattern": "^(0|[1-9]\\d*)$", "title": "Active Session Count" }, "includes_active_sessions": { "type": "boolean", "title": "Includes Active Sessions" }, "totals": { "$ref": "#/components/schemas/UsageAggregateTotals" }, "provider_breakdown": { "$ref": "#/components/schemas/UsageAggregateBreakdown" }, "model_breakdown": { "$ref": "#/components/schemas/UsageAggregateBreakdown" }, "cost": { "anyOf": [ { "$ref": "#/components/schemas/UsageCostRollup" }, { "type": "null" } ] }, "session_breakdown": { "anyOf": [ { "$ref": "#/components/schemas/UsageSessionAggregateBreakdown" }, { "type": "null" } ] }, "session_cost_breakdown": { "anyOf": [ { "$ref": "#/components/schemas/UsageSessionCostBreakdown" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "required": [ "scope", "time_basis", "session_filter_basis", "as_of", "start_at", "end_at", "accuracy", "matching_session_count", "active_session_count", "includes_active_sessions", "totals", "provider_breakdown", "model_breakdown", "cost" ], "title": "UsageRollupResponse"}UsageSessionAggregateBreakdown
Section titled “UsageSessionAggregateBreakdown”{ "properties": { "groups": { "items": { "$ref": "#/components/schemas/UsageSessionAggregateGroup" }, "type": "array", "maxItems": 100, "title": "Groups" }, "remainder": { "anyOf": [ { "$ref": "#/components/schemas/UsageSessionAggregateRemainder" }, { "type": "null" } ] }, "accuracy": { "$ref": "#/components/schemas/AggregateAccuracy" } }, "additionalProperties": false, "type": "object", "required": [ "groups", "remainder", "accuracy" ], "title": "UsageSessionAggregateBreakdown", "description": "Deterministic session groups plus an exact aggregate remainder."}