--- updatedAt: 2026-05-06T09:45:35.000Z agentTools: projectIndex: https://docs.cast.ai/llms.txt --- # Generate Cost Breakdown by Dimension Generate breakdown by dimension (user, api_key, or tag_key) # OpenAPI definition ```json { "openapi": "3.0.3", "servers": [ { "url": "https://api.cast.ai/", "description": "US endpoint" }, { "url": "https://api.eu.cast.ai/", "description": "EU endpoint" } ], "info": { "title": "AI Enabler", "version": "0.0.1" }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "paths": { "/ai-optimizer/v1beta/organizations/{id}:generateBreakdown": { "get": { "tags": [ "AnalyticsAPI" ], "summary": "Generate Cost Breakdown by Dimension", "description": "Generate breakdown by dimension (user, api_key, or tag_key)", "operationId": "AnalyticsAPI_GenerateBreakdown", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the organization.", "required": true, "schema": { "type": "string" } }, { "name": "dimension", "in": "query", "description": "Dimension to group by.", "schema": { "enum": [ "BREAKDOWN_DIMENSION_UNSPECIFIED", "BREAKDOWN_DIMENSION_USER", "BREAKDOWN_DIMENSION_API_KEY", "BREAKDOWN_DIMENSION_TAG_KEY", "BREAKDOWN_DIMENSION_TEAM", "BREAKDOWN_DIMENSION_AGENT_SOURCE", "BREAKDOWN_DIMENSION_SESSION", "BREAKDOWN_DIMENSION_MODEL", "BREAKDOWN_DIMENSION_WORKSPACE" ], "type": "string", "format": "enum" } }, { "name": "tagKey", "in": "query", "description": "Tag key to group by when dimension is BREAKDOWN_DIMENSION_TAG_KEY.", "schema": { "type": "string" } }, { "name": "startTime", "in": "query", "description": "Start time for the breakdown data. Defaults to 7 days ago.", "schema": { "type": "string", "format": "date-time" } }, { "name": "endTime", "in": "query", "description": "End time for the breakdown data. Defaults to now.", "schema": { "type": "string", "format": "date-time" } }, { "name": "filter", "in": "query", "description": "CEL expression for filtering results.", "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "Maximum number of items to return per page.", "schema": { "type": "integer", "format": "int32" } }, { "name": "pageToken", "in": "query", "description": "Page token from a previous response for cursor-based pagination.", "schema": { "type": "string" } }, { "name": "includeServiceAccounts", "in": "query", "description": "Whether to include service accounts in user dimension results.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateBreakdownResponse" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "BreakdownItem": { "type": "object", "properties": { "dimensionValue": { "type": "string", "description": "The value of the dimension: user ID, API key ID, tag value, team ID, agent\n source, session ID, model or workspace ID." }, "displayName": { "type": "string", "description": "Human-readable display name for the dimension value. For the session\n dimension, the name of the user who ran the session, or the owner's ID when\n it is not an organization user, such as a service account." }, "email": { "type": "string", "description": "Email address (populated for user dimension)." }, "totalCostUsd": { "type": "string", "description": "Total cost in USD for the period." }, "requestCount": { "type": "string", "description": "Total number of requests." }, "inputTokens": { "type": "string", "description": "Total input tokens." }, "outputTokens": { "type": "string", "description": "Total output tokens." }, "totalTokens": { "type": "string", "description": "Total tokens (input + output)." }, "percentOfTotal": { "type": "number", "description": "Percentage of total cost across all dimension values.", "format": "double" }, "prevPeriodCostUsd": { "type": "string", "description": "Cost in USD for the previous period (same duration before start_time)." }, "costTrendPct": { "type": "number", "description": "Percentage change in cost vs the previous period.", "format": "double" }, "topModels": { "type": "array", "items": { "type": "string" }, "description": "Top 3 models by cost for this dimension value." }, "lastActiveTime": { "type": "string", "description": "Time of the most recent request from this dimension value.", "format": "date-time" }, "autoCostUsd": { "type": "string", "description": "Cost in USD of the requests that named a virtual auto model; already included\n in total_cost_usd." }, "autoRequestCount": { "type": "string", "description": "Number of the requests that named a virtual auto model; already included in\n request_count." }, "autoModels": { "type": "array", "items": { "type": "string" }, "description": "Models the router picked for those auto requests, highest auto cost first\n (at most three)." } }, "description": "A single breakdown item representing one dimension value." }, "BreakdownTotals": { "type": "object", "properties": { "totalCostUsd": { "type": "string", "description": "Total cost in USD." }, "requestCount": { "type": "string", "description": "Total number of requests." }, "inputTokens": { "type": "string", "description": "Total input tokens." }, "outputTokens": { "type": "string", "description": "Total output tokens." }, "totalTokens": { "type": "string", "description": "Total tokens (input + output)." }, "autoCostUsd": { "type": "string", "description": "Cost in USD of the requests that named a virtual auto model." }, "autoRequestCount": { "type": "string", "description": "Number of the requests that named a virtual auto model." } }, "description": "Aggregated totals across all breakdown items." }, "GenerateBreakdownResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BreakdownItem" }, "description": "Breakdown items for the requested dimension." }, "totals": { "allOf": [ { "$ref": "#/components/schemas/BreakdownTotals" } ], "description": "Aggregated totals across all items (not just the current page)." }, "nextPageToken": { "type": "string", "description": "Token for the next page; empty if no more pages." } }, "description": "Response message containing cost breakdown data." }, "GoogleProtobufAny": { "type": "object", "properties": { "@type": { "type": "string", "description": "The type of the serialized message." } }, "additionalProperties": true, "description": "Contains an arbitrary serialized message along with a @type that describes the type of the serialized message." }, "Status": { "type": "object", "properties": { "code": { "type": "integer", "description": "The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].", "format": "int32" }, "message": { "type": "string", "description": "A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client." }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleProtobufAny" }, "description": "A list of messages that carry the error details. There is a common set of message types for APIs to use." } }, "description": "The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors)." } } }, "tags": [ { "name": "AnalyticsAPI", "description": "Provides an API to retrieve analytics data for AI Enabler usage." } ] } ```