{ "openapi": "3.0.0", "components": { "examples": {}, "headers": {}, "parameters": {}, "requestBodies": {}, "responses": {}, "schemas": { "Metadata": { "description": "Custom Metadata Object\n\nA flexible key-value object for storing custom metadata.\nUse this to attach arbitrary data to resources like usage events and end users.\n\nKeys must be strings. Values can be any JSON-serializable type (string, number, boolean, array, object, null).", "properties": {}, "type": "object", "additionalProperties": {} }, "UsageEventItemDTO": { "description": "A single usage event returned by GET /usage/events.", "properties": { "id": { "type": "string", "description": "Unique event ID (UUID)." }, "event_type": { "type": "string", "description": "Event type label. Events ingested via POST /usage-events always carry 'ai.inference'." }, "metric_name": { "type": "string", "description": "Metric name, stored lowercase. Events ingested via POST /usage-events always carry 'tokens'." }, "quantity": { "type": "number", "format": "double", "description": "Quantity consumed. For events ingested via POST /usage-events this is total tokens (input plus output)." }, "event_timestamp": { "type": "string", "description": "When the event occurred (ISO 8601 UTC)." }, "metadata": { "$ref": "#/components/schemas/Metadata", "description": "Metadata supplied on the usage event, plus mapped attribution keys (provider, feature, agent_id, workflow_id, units)." } }, "required": [ "id", "event_type", "metric_name", "quantity", "event_timestamp" ], "type": "object", "additionalProperties": false }, "QueryUsageEventsResponseDTO": { "properties": { "events": { "items": { "$ref": "#/components/schemas/UsageEventItemDTO" }, "type": "array", "description": "Array of usage events." }, "total": { "type": "number", "format": "double", "description": "Total number of events matching the query." }, "limit": { "type": "number", "format": "double", "description": "Number of events returned in this page." }, "offset": { "type": "number", "format": "double", "description": "Offset for pagination." } }, "required": [ "events", "total", "limit", "offset" ], "type": "object", "additionalProperties": false }, "ApiErrorEnvelopeDTO": { "description": "Standard Error Envelope\n\nEvery error returned by the Bear Lumen API uses this envelope, across all\n4xx and 5xx status codes. Read `error.code` for programmatic handling and\nquote `error.correlationId` when contacting support so we can trace the\nexact request.\n\nThe only exception: HMAC signature failures on the usage ingestion\nendpoints return a flat `{ \"error\": string, \"code\": string }` body instead\nof this envelope.", "properties": { "success": { "type": "boolean", "enum": [ false ], "nullable": false, "description": "Always false for error responses.\nCheck this field to distinguish errors from successful responses.", "example": false }, "error": { "properties": { "details": { "properties": { "retryable": { "type": "boolean", "description": "True when retrying the same request may succeed, for example after\na rate limit window passes or a temporary outage resolves. When\nfalse, fix the request before retrying." }, "supportMessage": { "type": "string", "description": "How to get help with this failure. Included on server-side errors\nand already contains the correlationId to quote." }, "userMessage": { "type": "string", "description": "Plain-language summary of the failure, safe to show to your own\nusers." } }, "additionalProperties": {}, "type": "object", "description": "Additional error context and resolution guidance." }, "referenceCode": { "type": "string", "description": "Same value as `correlationId`.", "deprecated": true }, "correlationId": { "type": "string", "description": "Unique reference for this specific failure.\nQuote this ID when contacting support so we can locate the exact\nrequest in our logs. Also returned in the `X-Correlation-ID`\nresponse header.", "example": "OLIVE-DINOSAUR-1b2fE4" }, "message": { "type": "string", "description": "Human-readable explanation of what went wrong and, where possible,\nwhat to change before retrying.", "example": "start_date must be on or before end_date." }, "code": { "type": "string", "description": "Machine-readable error code for programmatic handling.\nCommon codes: `VALIDATION_ERROR` (400), `UNAUTHORIZED` (401),\n`FORBIDDEN` (403), `NOT_FOUND` (404), `RATE_LIMIT_EXCEEDED` (429),\n`INTERNAL_SERVER_ERROR` (500).\nBranch on this field, not on `message` (message wording may change).", "example": "VALIDATION_ERROR" } }, "required": [ "correlationId", "message", "code" ], "type": "object", "description": "Details of the error that caused the request to fail." }, "meta": { "properties": { "method": { "type": "string", "description": "HTTP method of the request that failed.", "example": "GET" }, "path": { "type": "string", "description": "Path of the request that failed.", "example": "/v1/cost-data/summary" }, "requestId": { "type": "string", "description": "Unique identifier for this request, useful when correlating with\nyour own request logs.", "example": "req_a1b2c3d4e5f6" }, "timestamp": { "type": "string", "description": "ISO 8601 UTC timestamp when the error response was generated.", "example": "2026-07-08T12:34:56.789Z", "format": "date-time" } }, "required": [ "timestamp" ], "type": "object", "description": "Metadata about the failed request." } }, "required": [ "success", "error", "meta" ], "type": "object", "additionalProperties": false, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "start_date must be on or before end_date.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "start_date must be on or before end_date.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/summary", "method": "GET" } } }, "UsageAggregationDTO": { "properties": { "metric_name": { "type": "string", "description": "Metric name." }, "total_quantity": { "type": "number", "format": "double", "description": "Total quantity consumed." }, "event_count": { "type": "number", "format": "double", "description": "Number of events." }, "first_event_at": { "type": "string", "description": "Timestamp of first event." }, "last_event_at": { "type": "string", "description": "Timestamp of last event." } }, "required": [ "metric_name", "total_quantity", "event_count", "first_event_at", "last_event_at" ], "type": "object", "additionalProperties": false }, "QueryUsageAggregationResponseDTO": { "properties": { "aggregations": { "items": { "$ref": "#/components/schemas/UsageAggregationDTO" }, "type": "array", "description": "Aggregated usage by metric." }, "period_start": { "type": "string", "description": "Start of the period." }, "period_end": { "type": "string", "description": "End of the period." }, "total_events": { "type": "number", "format": "double", "description": "Total number of events in this period." } }, "required": [ "aggregations", "period_start", "period_end", "total_events" ], "type": "object", "additionalProperties": false }, "UsageMetricSummaryDTO": { "description": "Per-metric totals within a usage summary.", "properties": { "metric_name": { "type": "string", "description": "Metric name, stored lowercase (e.g. 'tokens')." }, "total_quantity": { "type": "number", "format": "double", "description": "Total quantity consumed for this metric in the period." }, "event_count": { "type": "number", "format": "double", "description": "Number of events recorded for this metric in the period." } }, "required": [ "metric_name", "total_quantity", "event_count" ], "type": "object", "additionalProperties": false }, "QueryUsageSummaryResponseDTO": { "properties": { "user_id": { "type": "string", "description": "Bear Lumen account user ID (UUID) that owns the queried usage: the user your API key belongs to. Not the end-user user_id you send on POST /usage-events." }, "period_start": { "type": "string", "description": "Start of the period." }, "period_end": { "type": "string", "description": "End of the period." }, "total_events": { "type": "number", "format": "double", "description": "Total number of events." }, "metrics": { "items": { "$ref": "#/components/schemas/UsageMetricSummaryDTO" }, "type": "array", "description": "Summary by metric." } }, "required": [ "user_id", "period_start", "period_end", "total_events", "metrics" ], "type": "object", "additionalProperties": false }, "RateEstimationModelDTO": { "description": "Effective estimation rates for one model, in USD per million tokens,\nserialized as decimal strings.", "properties": { "model_slug": { "type": "string", "description": "The model identifier rates apply to (e.g., \"gpt-4o\",\n\"claude-sonnet-4-5\"). Match your call's model name against these slugs\nby longest prefix, the same rule the cost ledger uses (e.g.,\n\"gpt-4o-2024-05-13\" matches \"gpt-4o\")." }, "input_cost_per_million": { "type": "string", "description": "Cost per million input tokens (USD, decimal string)." }, "cache_creation_cost_per_million": { "type": "string", "nullable": true, "description": "Cost per million cache-creation input tokens (USD, decimal string).\nAlready resolved: when the model has no explicit cache-creation rate,\nthis carries the same derived rate the cost ledger applies. A null means\nthe token class cannot be priced for this model; treat those tokens as\nunpriced in estimates." }, "cache_read_cost_per_million": { "type": "string", "nullable": true, "description": "Cost per million cache-read input tokens (USD, decimal string). Resolved\nthe same way as cache_creation_cost_per_million; null means the token\nclass cannot be priced for this model." }, "output_cost_per_million": { "type": "string", "description": "Cost per million output tokens (USD, decimal string)." }, "reasoning_cost_per_million": { "type": "string", "nullable": true, "description": "Cost per million reasoning tokens (USD, decimal string). Already\nresolved: models without an explicit reasoning rate carry the output\nrate here, matching the cost ledger. A null means the token class cannot\nbe priced for this model." } }, "required": [ "model_slug", "input_cost_per_million", "cache_creation_cost_per_million", "cache_read_cost_per_million", "output_cost_per_million", "reasoning_cost_per_million" ], "type": "object", "additionalProperties": false }, "RateEstimationTableResponseDTO": { "description": "Rate estimation table response.", "properties": { "items": { "items": { "$ref": "#/components/schemas/RateEstimationModelDTO" }, "type": "array", "description": "Effective per-model estimation rates for your organization, sorted by\nmodel_slug. Includes any organization-specific rates agreed with Bear\nLumen in place of the standard rates. Models priced per unit rather than\nper token (e.g., audio or image generation) are not listed; estimate\nthose from your own unit assumptions." } }, "required": [ "items" ], "type": "object", "additionalProperties": false }, "PingResponseDTO": { "description": "Response from the connectivity ping endpoint.", "properties": { "ok": { "type": "boolean", "description": "Always true when the request succeeds." }, "organization_id": { "type": "string", "description": "Organization ID associated with the API key." } }, "required": [ "ok", "organization_id" ], "type": "object", "additionalProperties": false }, "MarginDataSummaryDTO": { "description": "Organization-level margin summary. Includes ALL revenue and ALL cost for\nthe period, attributed and unattributed.", "properties": { "total_revenue": { "type": "string", "description": "Total revenue for the period, decimal string in USD. Returns \"0\" when no\nrevenue has been synced from your connected Stripe account.", "example": "14320.00" }, "total_cost": { "type": "string", "description": "Total cost for the period, decimal string in USD.", "example": "7210.50" }, "margin_amount": { "type": "string", "description": "Revenue minus cost for the period, decimal string in USD. Negative when\ncost exceeds revenue.", "example": "7109.50" }, "margin_percent": { "type": "number", "format": "double", "nullable": true, "description": "Margin percentage ((revenue - cost) / revenue * 100), rounded to 2\ndecimal places. Null when revenue for the period is zero (division by\nzero is undefined).", "example": 49.65 }, "profitability_category": { "type": "string", "enum": [ "profitable", "break-even", "unprofitable" ], "description": "Profitability classification. `profitable` when the margin percentage is\nabove 20, `break-even` between 0 and 20 (or when there is no activity at\nall), `unprofitable` below 0 (or when there is cost with zero revenue).", "example": "profitable" }, "revenue_record_count": { "type": "number", "format": "double", "description": "Number of revenue records included in total_revenue.", "example": 342 }, "cost_record_count": { "type": "number", "format": "double", "description": "Number of cost records included in total_cost.", "example": 48210 }, "unattributed_revenue": { "type": "string", "description": "Revenue in the window that could not be attributed to a specific end\nuser, decimal string in USD. Computed as a raw sum of revenue records\nwhose recognition period starts inside the window, which is a different\nbasis than the accrual-recognized total_revenue, so treat it as a\ncompanion diagnostic rather than a strict subset of total_revenue.", "example": "1250.00" }, "unattributed_cost": { "type": "string", "description": "Cost not attributed to any end user, decimal string in USD. Included in\ntotal_cost but absent from the per-end-user breakdown.", "example": "430.00" } }, "required": [ "total_revenue", "total_cost", "margin_amount", "margin_percent", "profitability_category", "revenue_record_count", "cost_record_count", "unattributed_revenue", "unattributed_cost" ], "type": "object", "additionalProperties": false }, "MarginDataWarningDTO": { "description": "A data-quality warning attached to margin responses.", "properties": { "type": { "type": "string", "enum": [ "unattributed_revenue", "unattributed_cost", "revenue_not_connected" ], "description": "Warning category. `unattributed_revenue` means revenue records exist that\nare not linked to any end user; `unattributed_cost` means cost records\nexist that are not linked to any end user. Unattributed amounts are\nincluded in organization totals but absent from the per-end-user\nbreakdown. `revenue_not_connected` means your organization has no active\nStripe revenue connection, so a `total_revenue` of \"0\" reflects a missing\nconnection rather than a genuine zero-revenue period; connect Stripe to\npopulate revenue and margin.", "example": "unattributed_revenue" }, "count": { "type": "number", "format": "double", "description": "Number of records affected by this warning. `0` for the\n`revenue_not_connected` warning, which reflects connection status rather\nthan a set of records.", "example": 8 }, "message": { "type": "string", "description": "Human-readable description of the warning.", "example": "8 revenue record(s) without customer attribution" } }, "required": [ "type", "count", "message" ], "type": "object", "additionalProperties": false }, "MarginDataSummaryResponseDTO": { "description": "Margin summary response DTO.", "properties": { "summary": { "$ref": "#/components/schemas/MarginDataSummaryDTO", "description": "Organization-level margin summary for the requested period." }, "warnings": { "items": { "$ref": "#/components/schemas/MarginDataWarningDTO" }, "type": "array", "description": "Data-quality warnings about unattributed revenue or cost. Empty when all records are attributed." } }, "required": [ "summary", "warnings" ], "type": "object", "additionalProperties": false }, "MarginDataByEndUserItemDTO": { "description": "Margin data for a single end user.", "properties": { "end_user_id": { "type": "string", "description": "Bear Lumen's internal end-user ID (UUID). Pass this value as the\nend_user_id filter on GET /margin-data/trend. This is not the external ID\nyou send on usage events.", "example": "5c1d9a1e-7b6f-4c2d-9e8a-3f1b2c4d5e6f" }, "end_user_name": { "type": "string", "description": "Display name of the end user.", "example": "Acme Corp" }, "revenue": { "type": "string", "description": "Revenue attributed to this end user for the period, decimal string in USD.", "example": "9800.00" }, "cost": { "type": "string", "description": "Cost attributed to this end user for the period, decimal string in USD.", "example": "3260.00" }, "margin_amount": { "type": "string", "description": "Revenue minus cost for this end user, decimal string in USD. Negative\nwhen cost exceeds revenue.", "example": "6540.00" }, "margin_percent": { "type": "number", "format": "double", "nullable": true, "description": "Margin percentage ((revenue - cost) / revenue * 100), rounded to 2\ndecimal places. Null when this end user's revenue for the period is zero.", "example": 66.73 }, "profitability_category": { "type": "string", "enum": [ "profitable", "break-even", "unprofitable" ], "description": "Profitability classification. `profitable` when the margin percentage is\nabove 20, `break-even` between 0 and 20 (or when there is no activity at\nall), `unprofitable` below 0 (or when there is cost with zero revenue).", "example": "profitable" } }, "required": [ "end_user_id", "end_user_name", "revenue", "cost", "margin_amount", "margin_percent", "profitability_category" ], "type": "object", "additionalProperties": false }, "MarginDataByEndUserResponseDTO": { "description": "Per-end-user margin response DTO.", "properties": { "end_users": { "items": { "$ref": "#/components/schemas/MarginDataByEndUserItemDTO" }, "type": "array", "description": "Per-end-user margin rows, sorted by profitability with the least profitable first." }, "org_total": { "$ref": "#/components/schemas/MarginDataSummaryDTO", "description": "Organization total for the period. Includes ALL revenue and ALL cost\n(attributed plus unattributed), so its totals can exceed the sums of the\nend_users rows." }, "warnings": { "items": { "$ref": "#/components/schemas/MarginDataWarningDTO" }, "type": "array", "description": "Data-quality warnings about unattributed revenue or cost. Empty when all records are attributed." } }, "required": [ "end_users", "org_total", "warnings" ], "type": "object", "additionalProperties": false }, "MarginDataTrendDataPointDTO": { "description": "Margin trend data point DTO.", "properties": { "date": { "type": "string", "description": "Start of the period bucket (ISO 8601, UTC). Buckets are days, weeks, or\nmonths depending on the response granularity.", "example": "2026-01-01T00:00:00.000Z" }, "revenue": { "type": "string", "description": "Revenue for this period bucket, decimal string in USD.", "example": "612.00" }, "cost": { "type": "string", "description": "Cost for this period bucket, decimal string in USD.", "example": "208.40" }, "margin_amount": { "type": "string", "description": "Revenue minus cost for this period bucket, decimal string in USD.\nNegative when cost exceeds revenue.", "example": "403.60" }, "margin_percent": { "type": "number", "format": "double", "nullable": true, "description": "Margin percentage ((revenue - cost) / revenue * 100), rounded to 2\ndecimal places. Null when revenue for this period bucket is zero.", "example": 65.95 } }, "required": [ "date", "revenue", "cost", "margin_amount", "margin_percent" ], "type": "object", "additionalProperties": false }, "MarginDataTrendResponseDTO": { "description": "Margin trend response DTO.", "properties": { "data_points": { "items": { "$ref": "#/components/schemas/MarginDataTrendDataPointDTO" }, "type": "array", "description": "Time-ordered margin data points. Periods with no revenue and no cost\nactivity are omitted rather than returned as zero values; zero-fill\nclient-side if you need a continuous series." }, "granularity": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "Size of each period bucket, chosen from the requested date range:\n`daily` for ranges of 30 days or less, `weekly` for 31 to 90 days,\n`monthly` for more than 90 days.", "example": "daily" } }, "required": [ "data_points", "granularity" ], "type": "object", "additionalProperties": false }, "InsightsPeriodBoundDTO": { "description": "One analysis period boundary: the half-open UTC range [start, end).", "properties": { "start": { "type": "string", "description": "ISO 8601 date string." }, "end": { "type": "string", "description": "ISO 8601 date string." } }, "required": [ "start", "end" ], "type": "object", "additionalProperties": false }, "InsightsPeriodDTO": { "description": "The two periods every insight compares: the current analysis window and the prior window of equal length.", "properties": { "current": { "$ref": "#/components/schemas/InsightsPeriodBoundDTO", "description": "Current analysis period." }, "prior": { "$ref": "#/components/schemas/InsightsPeriodBoundDTO", "description": "Prior comparison period. Auto-derived as the window of equal length immediately preceding start, or taken from prior_start and prior_end when both are provided." } }, "required": [ "current", "prior" ], "type": "object", "additionalProperties": false, "example": { "current": { "start": "2026-03-01T00:00:00.000Z", "end": "2026-03-31T00:00:00.000Z" }, "prior": { "start": "2026-02-01T00:00:00.000Z", "end": "2026-02-28T00:00:00.000Z" } } }, "PeriodComparisonDTO": { "description": "A current-versus-prior comparison for one metric. Units depend on the consuming field (USD dollars for cost and revenue, counts for requests and end users).", "properties": { "current": { "type": "number", "format": "double", "description": "Current period value." }, "prior": { "type": "number", "format": "double", "description": "Prior period value." }, "change_percent": { "type": "number", "format": "double", "nullable": true, "description": "Percent change from prior to current. Null when prior is 0 and current > 0 (new entry)." } }, "required": [ "current", "prior", "change_percent" ], "type": "object", "additionalProperties": false, "example": { "current": 12500.5, "prior": 10200.3, "change_percent": 22.5 } }, "MarginComparisonDTO": { "description": "A current-versus-prior margin comparison. Values are margin percentages; the change is expressed in percentage points.", "properties": { "current": { "type": "number", "format": "double", "description": "Current period margin percentage." }, "prior": { "type": "number", "format": "double", "description": "Prior period margin percentage." }, "change_points": { "type": "number", "format": "double", "description": "Percentage point change (current - prior)." } }, "required": [ "current", "prior", "change_points" ], "type": "object", "additionalProperties": false, "example": { "current": 45.2, "prior": 42.8, "change_points": 2.4 } }, "InsightsTotalsDTO": { "description": "Headline totals for the period: cost, revenue, margin, request volume, and active end users, each compared to the prior period.", "properties": { "cost": { "$ref": "#/components/schemas/PeriodComparisonDTO", "description": "Total cost comparison. Values are USD dollars." }, "revenue": { "$ref": "#/components/schemas/PeriodComparisonDTO", "description": "Total revenue comparison. Values are USD dollars." }, "margin": { "$ref": "#/components/schemas/MarginComparisonDTO", "description": "Overall margin comparison (percentage points)." }, "request_count": { "$ref": "#/components/schemas/PeriodComparisonDTO", "description": "Total request count comparison." }, "active_end_users": { "$ref": "#/components/schemas/PeriodComparisonDTO", "description": "Active end user count comparison." } }, "required": [ "cost", "revenue", "margin", "request_count", "active_end_users" ], "type": "object", "additionalProperties": false, "example": { "cost": { "current": 12500, "prior": 10200, "change_percent": 22.5 }, "revenue": { "current": 25000, "prior": 20000, "change_percent": 25 }, "margin": { "current": 50, "prior": 49, "change_points": 1 }, "request_count": { "current": 100000, "prior": 80000, "change_percent": 25 }, "active_end_users": { "current": 150, "prior": 120, "change_percent": 25 } } }, "CostPerEndUserDistributionDTO": { "description": "Cost-per-end-user distribution. Mean, median, std_dev, and percentile statistics are USD dollars.", "properties": { "mean": { "type": "number", "format": "double", "description": "Arithmetic mean." }, "median": { "type": "number", "format": "double", "description": "Median (50th percentile)." }, "std_dev": { "type": "number", "format": "double", "description": "Population standard deviation." }, "p25": { "type": "number", "format": "double", "description": "25th percentile." }, "p75": { "type": "number", "format": "double", "description": "75th percentile." }, "p90": { "type": "number", "format": "double", "description": "90th percentile." }, "p99": { "type": "number", "format": "double", "description": "99th percentile." }, "skewness": { "type": "number", "format": "double", "nullable": true, "description": "Fisher-Pearson skewness. Null if fewer than 3 users or zero variance." }, "gini": { "type": "number", "format": "double", "nullable": true, "description": "Gini coefficient (0 = perfect equality, 1 = maximum inequality). Null if fewer than 2 users." }, "top_decile_share": { "type": "number", "format": "double", "nullable": true, "description": "Percentage of total cost from the top 10% of users. Null if insufficient data." } }, "required": [ "mean", "median", "std_dev", "p25", "p75", "p90", "p99", "skewness", "gini", "top_decile_share" ], "type": "object", "additionalProperties": false }, "PercentileDistributionDTO": { "properties": { "mean": { "type": "number", "format": "double", "description": "Arithmetic mean." }, "median": { "type": "number", "format": "double", "description": "Median (50th percentile)." }, "std_dev": { "type": "number", "format": "double", "description": "Population standard deviation." }, "p25": { "type": "number", "format": "double", "description": "25th percentile." }, "p75": { "type": "number", "format": "double", "description": "75th percentile." }, "p90": { "type": "number", "format": "double", "description": "90th percentile." }, "p99": { "type": "number", "format": "double", "description": "99th percentile." } }, "required": [ "mean", "median", "std_dev", "p25", "p75", "p90", "p99" ], "type": "object", "additionalProperties": false, "example": { "mean": 83.5, "median": 65.2, "std_dev": 45.1, "p25": 30, "p75": 120, "p90": 180, "p99": 350 } }, "MarginPerEndUserDistributionDTO": { "properties": { "mean": { "type": "number", "format": "double", "description": "Arithmetic mean." }, "median": { "type": "number", "format": "double", "description": "Median (50th percentile)." }, "std_dev": { "type": "number", "format": "double", "description": "Population standard deviation." }, "p25": { "type": "number", "format": "double", "description": "25th percentile." }, "p75": { "type": "number", "format": "double", "description": "75th percentile." }, "p90": { "type": "number", "format": "double", "description": "90th percentile." }, "p99": { "type": "number", "format": "double", "description": "99th percentile." }, "skewness": { "type": "number", "format": "double", "nullable": true, "description": "Fisher-Pearson skewness. Null if fewer than 3 users or zero variance." }, "below_zero_count": { "type": "number", "format": "double", "description": "Number of end users with negative margin." } }, "required": [ "mean", "median", "std_dev", "p25", "p75", "p90", "p99", "skewness", "below_zero_count" ], "type": "object", "additionalProperties": false }, "DailyCostDistributionDTO": { "description": "Daily cost distribution. Mean, median, std_dev, min, and max are USD dollars;\ncv is a dimensionless ratio.", "properties": { "mean": { "type": "number", "format": "double", "description": "Arithmetic mean of daily costs." }, "median": { "type": "number", "format": "double", "description": "Median daily cost." }, "std_dev": { "type": "number", "format": "double", "description": "Population standard deviation." }, "min": { "type": "number", "format": "double", "description": "Minimum daily cost." }, "max": { "type": "number", "format": "double", "description": "Maximum daily cost." }, "cv": { "type": "number", "format": "double", "description": "Coefficient of variation (std_dev / mean)." }, "trend": { "properties": { "r2": { "type": "number", "format": "double" }, "direction": { "type": "string", "enum": [ "increasing", "decreasing", "stable" ] }, "slope": { "type": "number", "format": "double" } }, "required": [ "r2", "direction", "slope" ], "type": "object", "nullable": true, "description": "Linear regression trend. Null if fewer than 2 data points." } }, "required": [ "mean", "median", "std_dev", "min", "max", "cv", "trend" ], "type": "object", "additionalProperties": false, "example": { "mean": 450.2, "median": 420, "std_dev": 80.5, "min": 200, "max": 850, "cv": 0.179, "trend": { "slope": 2.5, "direction": "increasing", "r2": 0.85 } } }, "InsightsDistributionsDTO": { "description": "Distributions block. Null when include parameter does not contain 'distributions'.", "properties": { "cost_per_end_user": { "allOf": [ { "$ref": "#/components/schemas/CostPerEndUserDistributionDTO" } ], "nullable": true, "description": "Cost distribution across end users, in USD dollars. Null when the period contains no qualifying data." }, "cost_per_request": { "allOf": [ { "$ref": "#/components/schemas/PercentileDistributionDTO" } ], "nullable": true, "description": "Cost-per-request distribution across end users, in USD dollars. Null when the period contains no qualifying data." }, "margin_per_end_user": { "allOf": [ { "$ref": "#/components/schemas/MarginPerEndUserDistributionDTO" } ], "nullable": true, "description": "Margin percentage distribution across end users. Null when the period contains no qualifying data." }, "daily_cost": { "allOf": [ { "$ref": "#/components/schemas/DailyCostDistributionDTO" } ], "nullable": true, "description": "Daily cost distribution with trend, in USD dollars. Null when the period contains no qualifying data." }, "requests_per_end_user": { "allOf": [ { "$ref": "#/components/schemas/PercentileDistributionDTO" } ], "nullable": true, "description": "Request count distribution across end users. Null when the period contains no qualifying data." } }, "required": [ "cost_per_end_user", "cost_per_request", "margin_per_end_user", "daily_cost", "requests_per_end_user" ], "type": "object", "additionalProperties": false }, "ModelMoverDTO": { "properties": { "value": { "type": "string", "description": "Model slug." }, "cost": { "type": "number", "format": "double", "description": "Current period cost (USD dollars)." }, "prior": { "type": "number", "format": "double", "description": "Prior period cost (USD dollars)." }, "change_percent": { "type": "number", "format": "double", "nullable": true, "description": "Percent change. Null when prior is 0 and current > 0 (new entry)." }, "share_percent": { "type": "number", "format": "double", "description": "Current period cost share (%)." }, "prior_share_percent": { "type": "number", "format": "double", "description": "Prior period cost share (%)." }, "z_score": { "type": "number", "format": "double", "nullable": true, "description": "Z-score of change relative to population. Null if all changes identical." }, "request_count": { "type": "number", "format": "double", "description": "Request count in current period." }, "avg_cost_per_request": { "type": "number", "format": "double", "description": "Average cost per request (USD dollars)." } }, "required": [ "value", "cost", "prior", "change_percent", "share_percent", "prior_share_percent", "z_score", "request_count", "avg_cost_per_request" ], "type": "object", "additionalProperties": false, "example": { "value": "gpt-4o", "cost": 5200, "prior": 3800, "change_percent": 36.8, "share_percent": 41.6, "prior_share_percent": 37.3, "z_score": 1.8, "request_count": 45000, "avg_cost_per_request": 0.116 } }, "ProviderMoverDTO": { "properties": { "value": { "type": "string", "description": "Provider slug." }, "cost": { "type": "number", "format": "double", "description": "Current period cost (USD dollars)." }, "prior": { "type": "number", "format": "double", "description": "Prior period cost (USD dollars)." }, "change_percent": { "type": "number", "format": "double", "nullable": true, "description": "Percent change. Null when prior is 0 and current > 0 (new entry)." }, "share_percent": { "type": "number", "format": "double", "description": "Current period cost share (%)." }, "prior_share_percent": { "type": "number", "format": "double", "description": "Prior period cost share (%)." }, "z_score": { "type": "number", "format": "double", "nullable": true, "description": "Z-score of change relative to population. Null if all changes identical." } }, "required": [ "value", "cost", "prior", "change_percent", "share_percent", "prior_share_percent", "z_score" ], "type": "object", "additionalProperties": false, "example": { "value": "anthropic", "cost": 8200, "prior": 6000, "change_percent": 36.7, "share_percent": 65.6, "prior_share_percent": 58.8, "z_score": 2.1 } }, "Record_string.number_": { "properties": {}, "additionalProperties": { "type": "number", "format": "double" }, "type": "object", "description": "A map of string keys to numeric values." }, "EndUserMoverDTO": { "properties": { "value": { "type": "string", "description": "End user external ID (the ID supplied on your usage events)." }, "cost": { "type": "number", "format": "double", "description": "Current period cost (USD dollars)." }, "prior": { "type": "number", "format": "double", "description": "Prior period cost (USD dollars)." }, "change_percent": { "type": "number", "format": "double", "nullable": true, "description": "Percent change. Null when prior is 0 and current > 0 (new entry)." }, "share_percent": { "type": "number", "format": "double", "description": "Current period cost share (%)." }, "z_score": { "type": "number", "format": "double", "nullable": true, "description": "Z-score of change relative to population. Null if all changes identical." }, "percentile": { "type": "number", "format": "double", "nullable": true, "description": "Percentile rank by cost. Null if no data." }, "margin": { "type": "number", "format": "double", "nullable": true, "description": "Current period margin percentage. Null if no revenue data." }, "margin_percentile": { "type": "number", "format": "double", "nullable": true, "description": "Percentile rank by margin. Null if no margin data." }, "model_mix": { "$ref": "#/components/schemas/Record_string.number_", "description": "Model mix: model slug to cost share percentage." } }, "required": [ "value", "cost", "prior", "change_percent", "share_percent", "z_score", "percentile", "margin", "margin_percentile", "model_mix" ], "type": "object", "additionalProperties": false }, "DimensionMoverDTO": { "properties": { "value": { "type": "string", "description": "Dimension value." }, "cost": { "type": "number", "format": "double", "description": "Current period cost (USD dollars)." }, "prior": { "type": "number", "format": "double", "description": "Prior period cost (USD dollars)." }, "change_percent": { "type": "number", "format": "double", "nullable": true, "description": "Percent change. Null when prior is 0 and current > 0 (new entry)." }, "share_percent": { "type": "number", "format": "double", "description": "Current period cost share (%)." }, "z_score": { "type": "number", "format": "double", "nullable": true, "description": "Z-score of change relative to population. Null if all changes identical." }, "end_user_count": { "type": "number", "format": "double", "description": "Number of distinct end users." }, "request_count": { "type": "number", "format": "double", "description": "Total request count." } }, "required": [ "value", "cost", "prior", "change_percent", "share_percent", "z_score", "end_user_count", "request_count" ], "type": "object", "additionalProperties": false }, "Record_string.DimensionMoverDTO-Array_": { "properties": {}, "additionalProperties": { "items": { "$ref": "#/components/schemas/DimensionMoverDTO" }, "type": "array" }, "type": "object", "description": "A map of string keys to DimensionMoverDTO array values." }, "InsightsTopMoversDTO": { "description": "Top movers ranked by absolute cost change between the current and prior period.", "properties": { "by_model": { "items": { "$ref": "#/components/schemas/ModelMoverDTO" }, "type": "array", "description": "Top movers by model." }, "by_provider": { "items": { "$ref": "#/components/schemas/ProviderMoverDTO" }, "type": "array", "description": "Top movers by provider." }, "by_end_user": { "items": { "$ref": "#/components/schemas/EndUserMoverDTO" }, "type": "array", "description": "Top movers by end user." }, "by_custom_dimension": { "$ref": "#/components/schemas/Record_string.DimensionMoverDTO-Array_", "description": "Top movers by custom dimension, keyed by dimension key." } }, "required": [ "by_model", "by_provider", "by_end_user", "by_custom_dimension" ], "type": "object", "additionalProperties": false }, "MarginOutlierDTO": { "properties": { "end_user": { "type": "string", "description": "End user external ID (the ID supplied on your usage events)." }, "margin": { "type": "number", "format": "double", "description": "Margin percentage." }, "deviation_from_mean": { "type": "number", "format": "double", "description": "Deviation from population mean (percentage points)." }, "z_score": { "type": "number", "format": "double", "nullable": true, "description": "Z-score (how many std devs below mean). Null if zero variance." }, "cost": { "type": "number", "format": "double", "description": "Total cost for this end user (USD dollars)." }, "model_mix": { "$ref": "#/components/schemas/Record_string.number_", "description": "Model mix: model slug to cost share percentage." } }, "required": [ "end_user", "margin", "deviation_from_mean", "z_score", "cost", "model_mix" ], "type": "object", "additionalProperties": false }, "InsightsCorrelationsDTO": { "description": "Pearson correlations between key metrics over the period, from -1 (inverse) to 1 (direct). Null values mean not enough data points to compute.", "properties": { "cost_vs_request_volume": { "type": "number", "format": "double", "nullable": true, "description": "Pearson correlation between cost and request volume per end user. Null if insufficient data." }, "margin_vs_model_mix": { "type": "number", "format": "double", "nullable": true, "description": "Pearson correlation between margin and model mix concentration (HHI). Null if insufficient data." } }, "required": [ "cost_vs_request_volume", "margin_vs_model_mix" ], "type": "object", "additionalProperties": false, "example": { "cost_vs_request_volume": 0.95, "margin_vs_model_mix": -0.34 } }, "UnmappedSpendDTO": { "description": "Spend that cannot yet be attributed to margin, split into two buckets:\ninstrumentation_gap_* is usage recorded without an end user ID (fix by passing\nan end user ID in your usage events); connect_billing_gap_* is spend for end\nusers with no connected Stripe revenue data (fix by connecting Stripe).\nPercent fields are 0, not null, when there is no spend.", "properties": { "instrumentation_gap_cents": { "type": "number", "format": "double", "description": "Spend recorded without an end user ID, in integer USD cents. Close this gap by passing an end user ID in your usage events." }, "instrumentation_gap_percent": { "type": "number", "format": "double", "description": "instrumentation_gap_cents as a percent of total spend. A real 0, not null, when there is no spend." }, "connect_billing_gap_cents": { "type": "number", "format": "double", "description": "Spend for end users with no connected Stripe revenue data, in integer USD cents. Close this gap by connecting Stripe." }, "connect_billing_gap_percent": { "type": "number", "format": "double", "description": "connect_billing_gap_cents as a percent of total spend. A real 0, not null, when there is no spend." } }, "required": [ "instrumentation_gap_cents", "instrumentation_gap_percent", "connect_billing_gap_cents", "connect_billing_gap_percent" ], "type": "object", "additionalProperties": false, "example": { "instrumentation_gap_cents": 1500, "instrumentation_gap_percent": 12.5, "connect_billing_gap_cents": 4200, "connect_billing_gap_percent": 35 } }, "InsightsSummaryResponseDTO": { "properties": { "period": { "$ref": "#/components/schemas/InsightsPeriodDTO", "description": "Analysis period metadata." }, "totals": { "$ref": "#/components/schemas/InsightsTotalsDTO", "description": "Period-over-period totals with change metrics." }, "distributions": { "allOf": [ { "$ref": "#/components/schemas/InsightsDistributionsDTO" } ], "nullable": true, "description": "Population distributions. Null when not requested via include parameter." }, "top_movers": { "$ref": "#/components/schemas/InsightsTopMoversDTO", "description": "Top movers by model, provider, end user, and custom dimensions." }, "margin_outliers": { "items": { "$ref": "#/components/schemas/MarginOutlierDTO" }, "type": "array", "description": "End users whose margin z-score is below -1.5. Empty when no outliers are found, when fewer than 2 end users have margin data, or when all margins are identical (zero variance)." }, "correlations": { "$ref": "#/components/schemas/InsightsCorrelationsDTO", "description": "Cross-metric Pearson correlations." }, "unmapped_spend": { "$ref": "#/components/schemas/UnmappedSpendDTO", "description": "Aggregated unmapped-spend breakdown." } }, "required": [ "period", "totals", "distributions", "top_movers", "margin_outliers", "correlations", "unmapped_spend" ], "type": "object", "additionalProperties": false }, "EndUserCostsSummaryResponseDTO": { "description": "End user cost summary response.", "properties": { "end_user_id": { "type": "string", "description": "Bear Lumen internal end-user ID (UUID). Use end_user_external_id / the externalId path parameter for lookups, not this value." }, "end_user_external_id": { "type": "string", "description": "End-user external ID: the identifier you supplied on usage events (the user_id field on POST /usage-events)." }, "end_user_name": { "type": "string", "description": "End-user display name." }, "current_period_cost": { "type": "string", "description": "Current period total cost (decimal string)." }, "previous_period_cost": { "type": "string", "description": "Previous period total cost (decimal string)." }, "change_amount": { "type": "string", "description": "Change amount (current - previous, decimal string)." }, "change_percent": { "type": "number", "format": "double", "nullable": true, "description": "Change percentage (null if previous is zero)." }, "event_count": { "type": "number", "format": "double", "description": "Number of events in current period." }, "period_start": { "type": "string", "description": "Period start date (ISO 8601)." }, "period_end": { "type": "string", "description": "Period end date (ISO 8601)." } }, "required": [ "end_user_id", "end_user_external_id", "end_user_name", "current_period_cost", "previous_period_cost", "change_amount", "change_percent", "event_count", "period_start", "period_end" ], "type": "object", "additionalProperties": false }, "EndUserCostsModelCostDTO": { "description": "End user model cost item.", "properties": { "model_slug": { "type": "string", "description": "Model slug." }, "provider_slug": { "type": "string", "description": "Provider slug; the literal value 'unknown' when the event's provider could not be resolved." }, "total_cost": { "type": "string", "description": "Total cost for this model (decimal string)." }, "input_tokens": { "type": "number", "format": "double", "description": "Input tokens used." }, "output_tokens": { "type": "number", "format": "double", "description": "Output tokens used." }, "cache_creation_input_tokens": { "type": "number", "format": "double", "nullable": true, "description": "Cache-creation input tokens; null = provider did not report." }, "cache_read_input_tokens": { "type": "number", "format": "double", "nullable": true, "description": "Cache-read input tokens; null = provider did not report." }, "reasoning_tokens": { "type": "number", "format": "double", "nullable": true, "description": "Reasoning tokens; null = not reported." }, "input_cost": { "type": "string", "description": "Input cost (USD, decimal string)." }, "output_cost": { "type": "string", "description": "Output cost (USD, decimal string)." }, "cache_creation_cost": { "type": "string", "nullable": true, "description": "Cache-creation cost (USD string); null = not reported." }, "cache_read_cost": { "type": "string", "nullable": true, "description": "Cache-read cost (USD string); null = not reported." }, "reasoning_cost": { "type": "string", "nullable": true, "description": "Reasoning cost (USD string); null = not reported." }, "event_count": { "type": "number", "format": "double", "description": "Number of events." }, "percent_of_total": { "type": "number", "format": "double", "description": "Percentage of end-user's total cost." } }, "required": [ "model_slug", "provider_slug", "total_cost", "input_tokens", "output_tokens", "cache_creation_input_tokens", "cache_read_input_tokens", "reasoning_tokens", "input_cost", "output_cost", "cache_creation_cost", "cache_read_cost", "reasoning_cost", "event_count", "percent_of_total" ], "type": "object", "additionalProperties": false }, "EndUserCostsModelBreakdownResponseDTO": { "description": "End user model breakdown response.", "properties": { "end_user_id": { "type": "string", "description": "Bear Lumen internal end-user ID (UUID). Use the externalId path parameter for lookups, not this value." }, "models": { "items": { "$ref": "#/components/schemas/EndUserCostsModelCostDTO" }, "type": "array", "description": "Cost breakdown by model." }, "total_cost": { "type": "string", "description": "Total cost across all models (decimal string)." } }, "required": [ "end_user_id", "models", "total_cost" ], "type": "object", "additionalProperties": false }, "EndUserCostsProviderCostDTO": { "description": "End user provider cost item.", "properties": { "provider_slug": { "type": "string", "description": "Provider slug; the literal value 'unknown' when the event's provider could not be resolved." }, "provider_name": { "type": "string", "description": "Provider display name; the literal value 'Unknown Provider' when the event's provider could not be resolved." }, "total_cost": { "type": "string", "description": "Total cost for this provider (decimal string)." }, "event_count": { "type": "number", "format": "double", "description": "Number of events." }, "percent_of_total": { "type": "number", "format": "double", "description": "Percentage of end-user's total cost." } }, "required": [ "provider_slug", "provider_name", "total_cost", "event_count", "percent_of_total" ], "type": "object", "additionalProperties": false }, "EndUserCostsProviderBreakdownResponseDTO": { "description": "End user provider breakdown response.", "properties": { "end_user_id": { "type": "string", "description": "Bear Lumen internal end-user ID (UUID). Use the externalId path parameter for lookups, not this value." }, "providers": { "items": { "$ref": "#/components/schemas/EndUserCostsProviderCostDTO" }, "type": "array", "description": "Cost breakdown by provider." }, "total_cost": { "type": "string", "description": "Total cost across all providers (decimal string)." } }, "required": [ "end_user_id", "providers", "total_cost" ], "type": "object", "additionalProperties": false }, "EndUserCostsTrendDataPointDTO": { "description": "End user trend data point.", "properties": { "date": { "type": "string", "description": "Period date (ISO 8601)." }, "cost": { "type": "string", "description": "Total cost for this period (decimal string)." }, "event_count": { "type": "number", "format": "double", "description": "Number of events." } }, "required": [ "date", "cost", "event_count" ], "type": "object", "additionalProperties": false }, "EndUserCostsTrendSeriesDTO": { "description": "End user trend series.", "properties": { "key": { "type": "string", "description": "Series key (the end-user external ID you queried)." }, "label": { "type": "string", "description": "Series label (currently the end-user external ID)." }, "data_points": { "items": { "$ref": "#/components/schemas/EndUserCostsTrendDataPointDTO" }, "type": "array", "description": "Data points. Periods with no events are omitted (not returned as zero-cost points); fill gaps client-side if your chart requires a continuous series." } }, "required": [ "key", "label", "data_points" ], "type": "object", "additionalProperties": false }, "EndUserCostsTrendResponseDTO": { "description": "End user cost trend response.", "properties": { "end_user_id": { "type": "string", "description": "Bear Lumen internal end-user ID (UUID). Use the externalId path parameter for lookups, not this value." }, "series": { "items": { "$ref": "#/components/schemas/EndUserCostsTrendSeriesDTO" }, "type": "array", "description": "Time-series data." }, "granularity": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "Granularity used for the series, selected from the date range: 30 days or less returns daily, 31-90 days weekly, longer ranges monthly." } }, "required": [ "end_user_id", "series", "granularity" ], "type": "object", "additionalProperties": false }, "EndUserCostsDimensionCostDTO": { "description": "End user dimension cost item.", "properties": { "attribution_value": { "type": "string", "description": "Dimension value; events missing the requested metadata key are grouped under the literal value 'Unassigned'." }, "total_cost": { "type": "string", "description": "Total cost for this dimension value (decimal string)." }, "input_tokens": { "type": "number", "format": "double", "description": "Input tokens used." }, "output_tokens": { "type": "number", "format": "double", "description": "Output tokens used." }, "cache_creation_input_tokens": { "type": "number", "format": "double", "nullable": true, "description": "Cache-creation input tokens; null = provider did not report." }, "cache_read_input_tokens": { "type": "number", "format": "double", "nullable": true, "description": "Cache-read input tokens; null = provider did not report." }, "reasoning_tokens": { "type": "number", "format": "double", "nullable": true, "description": "Reasoning tokens; null = not reported." }, "input_cost": { "type": "string", "description": "Input cost (USD, decimal string)." }, "output_cost": { "type": "string", "description": "Output cost (USD, decimal string)." }, "cache_creation_cost": { "type": "string", "nullable": true, "description": "Cache-creation cost (USD string); null = not reported." }, "cache_read_cost": { "type": "string", "nullable": true, "description": "Cache-read cost (USD string); null = not reported." }, "reasoning_cost": { "type": "string", "nullable": true, "description": "Reasoning cost (USD string); null = not reported." }, "event_count": { "type": "number", "format": "double", "description": "Number of events." }, "percent_of_total": { "type": "number", "format": "double", "description": "Percentage of end-user's total cost for this dimension." } }, "required": [ "attribution_value", "total_cost", "input_tokens", "output_tokens", "cache_creation_input_tokens", "cache_read_input_tokens", "reasoning_tokens", "input_cost", "output_cost", "cache_creation_cost", "cache_read_cost", "reasoning_cost", "event_count", "percent_of_total" ], "type": "object", "additionalProperties": false }, "EndUserCostsDimensionBreakdownResponseDTO": { "description": "End user dimension breakdown response.", "properties": { "end_user_id": { "type": "string", "description": "Bear Lumen internal end-user ID (UUID). Use the externalId path parameter for lookups, not this value." }, "items": { "items": { "$ref": "#/components/schemas/EndUserCostsDimensionCostDTO" }, "type": "array", "description": "Cost breakdown by dimension value." }, "total_cost": { "type": "string", "description": "Total cost across all dimension values (decimal string)." } }, "required": [ "end_user_id", "items", "total_cost" ], "type": "object", "additionalProperties": false }, "DimensionDataDefinitionDTO": { "description": "Dimension definition DTO.", "properties": { "id": { "type": "string", "description": "Dimension ID (UUID).", "example": "3f9c2b1c-7a5d-4e8f-9b2a-1c4d5e6f7a8b" }, "organization_id": { "type": "string", "description": "Organization ID (UUID).", "example": "9c8b7a6d-2e3f-4a5b-8c9d-0e1f2a3b4c5d" }, "name": { "type": "string", "description": "Display name." }, "key": { "type": "string", "description": "Metadata key." }, "description": { "type": "string", "description": "Optional description." }, "value_type": { "type": "string", "enum": [ "string", "number" ], "description": "Value type of the dimension: 'string' or 'number'.\nDimensions with value_type 'number' can be aggregated via\n/dimension-data/numeric-summary and /dimension-data/numeric-trend." }, "is_required": { "type": "boolean", "description": "When true, usage events missing this metadata key are rejected at ingestion." }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)." } }, "required": [ "id", "organization_id", "name", "key", "value_type", "is_required", "created_at" ], "type": "object", "additionalProperties": false }, "DimensionDataDefinitionsResponseDTO": { "description": "List dimensions response.", "properties": { "dimensions": { "items": { "$ref": "#/components/schemas/DimensionDataDefinitionDTO" }, "type": "array", "description": "List of dimension definitions." }, "total": { "type": "number", "format": "double", "description": "Total count." } }, "required": [ "dimensions", "total" ], "type": "object", "additionalProperties": false }, "DimensionDataCostBreakdownItemDTO": { "description": "Dimension cost breakdown item.", "properties": { "dimension_value": { "type": "string", "description": "Dimension value (e.g., \"team-ml\", \"region-us-east\").\nEvents missing this dimension key in their metadata are grouped as \"Unassigned\"." }, "total_cost": { "type": "string", "description": "Total cost for this dimension value (USD, decimal string)." }, "input_tokens": { "type": "number", "format": "double", "description": "Input tokens used." }, "output_tokens": { "type": "number", "format": "double", "description": "Output tokens used." }, "event_count": { "type": "number", "format": "double", "description": "Number of events." }, "percent_of_total": { "type": "number", "format": "double", "description": "Percentage of total organization cost." } }, "required": [ "dimension_value", "total_cost", "input_tokens", "output_tokens", "event_count", "percent_of_total" ], "type": "object", "additionalProperties": false }, "DimensionDataCostBreakdownResponseDTO": { "description": "Dimension cost breakdown response.", "properties": { "items": { "items": { "$ref": "#/components/schemas/DimensionDataCostBreakdownItemDTO" }, "type": "array", "description": "Cost breakdown by dimension value." }, "total_cost": { "type": "string", "description": "Total cost across all dimension values (USD, decimal string)." } }, "required": [ "items", "total_cost" ], "type": "object", "additionalProperties": false }, "DimensionDataTrendDataPointDTO": { "description": "Trend data point.", "properties": { "date": { "type": "string", "description": "Period date (ISO 8601)." }, "cost": { "type": "string", "description": "Total cost for this period (USD, decimal string)." }, "event_count": { "type": "number", "format": "double", "description": "Number of events." } }, "required": [ "date", "cost", "event_count" ], "type": "object", "additionalProperties": false }, "DimensionDataTrendSeriesDTO": { "description": "Trend series (for dimension-filtered trends).", "properties": { "key": { "type": "string", "description": "Series key (dimension value or 'total')." }, "label": { "type": "string", "description": "Series label for display." }, "data_points": { "items": { "$ref": "#/components/schemas/DimensionDataTrendDataPointDTO" }, "type": "array", "description": "Data points for this series." } }, "required": [ "key", "label", "data_points" ], "type": "object", "additionalProperties": false }, "DimensionDataCostTrendResponseDTO": { "description": "Cost trend response.\n\nReturns series array to support dimension-filtered trends:\n- No dimension: Single series with key='total'\n- Dimension key only: Top 5 dimension values + 'Other'\n- Dimension key + value: Single series for that value.", "properties": { "series": { "items": { "$ref": "#/components/schemas/DimensionDataTrendSeriesDTO" }, "type": "array", "description": "Time-series data as multiple series." }, "granularity": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "Granularity of the data." } }, "required": [ "series", "granularity" ], "type": "object", "additionalProperties": false }, "DimensionDataNumericSummaryResponseDTO": { "description": "Numeric dimension summary response.", "properties": { "value": { "type": "string", "nullable": true, "description": "Aggregated numeric value as string, or null when no events match." }, "event_count": { "type": "number", "format": "double", "description": "Number of events with a non-null value for this dimension." }, "aggregation": { "type": "string", "description": "Aggregation function used. One of: 'sum', 'avg', 'min', 'max'.", "example": "sum" }, "dimension_key": { "type": "string", "description": "Dimension key that was aggregated." } }, "required": [ "value", "event_count", "aggregation", "dimension_key" ], "type": "object", "additionalProperties": false }, "DimensionDataNumericTrendPointDTO": { "description": "Numeric dimension trend data point.", "properties": { "date": { "type": "string", "description": "Period date (ISO 8601)." }, "value": { "type": "string", "nullable": true, "description": "Aggregated numeric value as string, or null when no events in this period." }, "event_count": { "type": "number", "format": "double", "description": "Number of events in this period." } }, "required": [ "date", "value", "event_count" ], "type": "object", "additionalProperties": false }, "DimensionDataNumericTrendResponseDTO": { "description": "Numeric dimension trend response.", "properties": { "data_points": { "items": { "$ref": "#/components/schemas/DimensionDataNumericTrendPointDTO" }, "type": "array", "description": "Time-bucketed aggregated numeric values." }, "granularity": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "Granularity of the data." }, "aggregation": { "type": "string", "description": "Aggregation function used. One of: 'sum', 'avg', 'min', 'max'.", "example": "sum" }, "dimension_key": { "type": "string", "description": "Dimension key that was aggregated." } }, "required": [ "data_points", "granularity", "aggregation", "dimension_key" ], "type": "object", "additionalProperties": false }, "CostDataStatusCountsDTO": { "description": "Event status breakdown for the cost summary endpoint.\nCounts are organization-wide and not filtered by the request's time window.", "properties": { "completed": { "type": "number", "format": "double", "description": "Events with completed cost calculation (contributing to current/previous period totals)." }, "pending": { "type": "number", "format": "double", "description": "Events still being processed by the cost-calculation worker." }, "pending_rate_card": { "type": "number", "format": "double", "description": "Events accepted but waiting for a rate card to be configured for the model." }, "failed": { "type": "number", "format": "double", "description": "Events that failed cost calculation." } }, "required": [ "completed", "pending", "pending_rate_card", "failed" ], "type": "object", "additionalProperties": false }, "CostDataSummaryResponseDTO": { "description": "Cost summary response. When current_period_cost is '0', use event_count and\nstatus_counts to distinguish no events, events still processing, missing\nrate cards, or failed calculations. Both fields are optional and safe to\nignore.", "properties": { "current_period_cost": { "type": "string", "description": "Current period total cost (USD, decimal string)." }, "previous_period_cost": { "type": "string", "description": "Previous period total cost (USD, decimal string)." }, "change_amount": { "type": "string", "description": "Change amount (current - previous, USD, decimal string)." }, "change_percent": { "type": "number", "format": "double", "nullable": true, "description": "Change percentage (null if previous is zero)." }, "period_start": { "type": "string", "description": "Period start date (ISO 8601)." }, "period_end": { "type": "string", "description": "Period end date (ISO 8601)." }, "event_count": { "type": "number", "format": "double", "description": "Number of events that contributed to current_period_cost (completed events in the window). Optional for backwards compatibility." }, "status_counts": { "$ref": "#/components/schemas/CostDataStatusCountsDTO", "description": "Org-wide event status breakdown for empty-state and pipeline-lag diagnosis. Optional for backwards compatibility." } }, "required": [ "current_period_cost", "previous_period_cost", "change_amount", "change_percent", "period_start", "period_end" ], "type": "object", "additionalProperties": false }, "TimeWindow": { "type": "string", "enum": [ "current-period", "last-period", "last-7-days", "last-30-days", "last-90-days", "ytd", "last-year" ], "description": "Time window presets for dashboard queries.\n\nMUST stay in sync with the frontend's canonical type in\n`shared-frontend/lib/time-window.ts` (7 members). Fix for the\n2026-07-02 \"Invalid time_window: ytd\" 400: the frontend gained\n'last-90-days' / 'ytd' / 'last-year' while the backend kept only the\noriginal 4, so the /explore time chips crashed the cost summary." }, "CostDataEndUserCostDTO": { "description": "End user cost breakdown item.", "properties": { "end_user_id": { "type": "string", "description": "End user ID (UUID). 'unassigned' when events carry no end user. Note: this is Bear Lumen's internal end-user ID, not the external_id you supplied on usage events." }, "end_user_name": { "type": "string", "description": "End user display name." }, "total_cost": { "type": "string", "description": "Total cost for this end user." }, "input_tokens": { "type": "number", "format": "double", "description": "Input tokens used." }, "output_tokens": { "type": "number", "format": "double", "description": "Output tokens used." }, "cache_creation_input_tokens": { "type": "number", "format": "double", "nullable": true, "description": "Cache-creation input tokens; null = provider did not report." }, "cache_read_input_tokens": { "type": "number", "format": "double", "nullable": true, "description": "Cache-read input tokens; null = provider did not report." }, "reasoning_tokens": { "type": "number", "format": "double", "nullable": true, "description": "Reasoning tokens; null = not reported." }, "input_cost": { "type": "string", "description": "Input cost (USD, decimal string)." }, "output_cost": { "type": "string", "description": "Output cost (USD, decimal string)." }, "cache_creation_cost": { "type": "string", "nullable": true, "description": "Cache-creation cost (USD string); null = not reported." }, "cache_read_cost": { "type": "string", "nullable": true, "description": "Cache-read cost (USD string); null = not reported." }, "reasoning_cost": { "type": "string", "nullable": true, "description": "Reasoning cost (USD string); null = not reported." }, "event_count": { "type": "number", "format": "double", "description": "Number of events." }, "percent_of_total": { "type": "number", "format": "double", "description": "Percentage of total organization cost." } }, "required": [ "end_user_id", "end_user_name", "total_cost", "input_tokens", "output_tokens", "cache_creation_input_tokens", "cache_read_input_tokens", "reasoning_tokens", "input_cost", "output_cost", "cache_creation_cost", "cache_read_cost", "reasoning_cost", "event_count", "percent_of_total" ], "type": "object", "additionalProperties": false }, "CostDataEndUserBreakdownResponseDTO": { "description": "End user breakdown response.", "properties": { "end_users": { "items": { "$ref": "#/components/schemas/CostDataEndUserCostDTO" }, "type": "array", "description": "Cost breakdown by end user." }, "total_cost": { "type": "string", "description": "Total cost across all end users." } }, "required": [ "end_users", "total_cost" ], "type": "object", "additionalProperties": false }, "CostDataProviderCostDTO": { "description": "Provider cost breakdown item.", "properties": { "provider_id": { "type": "string", "description": "Provider ID (UUID); 'unknown' when the event could not be matched to a catalog provider." }, "provider_slug": { "type": "string", "description": "Provider slug. Uses the provider string reported on your usage events when present, otherwise the catalog slug; 'unknown' when unresolvable." }, "provider_name": { "type": "string", "description": "Provider name. Uses the provider string reported on your usage events when present, otherwise the catalog display name; 'Unknown' if unresolvable." }, "total_cost": { "type": "string", "description": "Total cost for this provider." }, "event_count": { "type": "number", "format": "double", "description": "Number of events." }, "percent_of_total": { "type": "number", "format": "double", "description": "Percentage of total organization cost." } }, "required": [ "provider_id", "provider_slug", "provider_name", "total_cost", "event_count", "percent_of_total" ], "type": "object", "additionalProperties": false }, "CostDataProviderBreakdownResponseDTO": { "description": "Provider breakdown response.", "properties": { "providers": { "items": { "$ref": "#/components/schemas/CostDataProviderCostDTO" }, "type": "array", "description": "Cost breakdown by provider." }, "total_cost": { "type": "string", "description": "Total cost across all providers." } }, "required": [ "providers", "total_cost" ], "type": "object", "additionalProperties": false }, "CostDataModelCostDTO": { "description": "Model cost breakdown item.", "properties": { "model_slug": { "type": "string", "description": "Model slug." }, "provider_slug": { "type": "string", "description": "Provider slug; 'unknown' when the model could not be matched to a catalog provider." }, "total_cost": { "type": "string", "description": "Total cost for this model." }, "input_tokens": { "type": "number", "format": "double", "description": "Input tokens used." }, "output_tokens": { "type": "number", "format": "double", "description": "Output tokens used." }, "cache_creation_input_tokens": { "type": "number", "format": "double", "nullable": true, "description": "Cache-creation input tokens; null = provider did not report." }, "cache_read_input_tokens": { "type": "number", "format": "double", "nullable": true, "description": "Cache-read input tokens; null = provider did not report." }, "reasoning_tokens": { "type": "number", "format": "double", "nullable": true, "description": "Reasoning tokens; null = not reported." }, "input_cost": { "type": "string", "description": "Input cost (USD, decimal string)." }, "output_cost": { "type": "string", "description": "Output cost (USD, decimal string)." }, "cache_creation_cost": { "type": "string", "nullable": true, "description": "Cache-creation cost (USD string); null = not reported." }, "cache_read_cost": { "type": "string", "nullable": true, "description": "Cache-read cost (USD string); null = not reported." }, "reasoning_cost": { "type": "string", "nullable": true, "description": "Reasoning cost (USD string); null = not reported." }, "event_count": { "type": "number", "format": "double", "description": "Number of events." }, "percent_of_total": { "type": "number", "format": "double", "description": "Percentage of total organization cost." } }, "required": [ "model_slug", "provider_slug", "total_cost", "input_tokens", "output_tokens", "cache_creation_input_tokens", "cache_read_input_tokens", "reasoning_tokens", "input_cost", "output_cost", "cache_creation_cost", "cache_read_cost", "reasoning_cost", "event_count", "percent_of_total" ], "type": "object", "additionalProperties": false }, "CostDataModelBreakdownResponseDTO": { "description": "Model breakdown response.", "properties": { "models": { "items": { "$ref": "#/components/schemas/CostDataModelCostDTO" }, "type": "array", "description": "Cost breakdown by model." }, "total_cost": { "type": "string", "description": "Total cost across all models." } }, "required": [ "models", "total_cost" ], "type": "object", "additionalProperties": false }, "CostDataTrendDataPointDTO": { "description": "Trend data point.", "properties": { "date": { "type": "string", "description": "Period date (ISO 8601)." }, "cost": { "type": "string", "description": "Total cost for this period." }, "event_count": { "type": "number", "format": "double", "description": "Number of events." } }, "required": [ "date", "cost", "event_count" ], "type": "object", "additionalProperties": false }, "CostDataTrendSeriesDTO": { "description": "Trend series (for dimension-filtered trends).", "properties": { "key": { "type": "string", "description": "Series key: 'total' for the unfiltered series, the dimension value for dimension series, or the end user ID when filtered by end_user_id." }, "label": { "type": "string", "description": "Series label for display." }, "data_points": { "items": { "$ref": "#/components/schemas/CostDataTrendDataPointDTO" }, "type": "array", "description": "Data points for this series." } }, "required": [ "key", "label", "data_points" ], "type": "object", "additionalProperties": false }, "CostDataTrendResponseDTO": { "description": "Cost trend response\n\nReturns a series array to support filtered trends:\n- No filter params: Single series with key='total'\n- Dimension key only: Top 5 dimension values + 'Other'\n- Dimension key + value: Single series for that value\n- End user ID: Single series keyed by that end user ID.", "properties": { "series": { "items": { "$ref": "#/components/schemas/CostDataTrendSeriesDTO" }, "type": "array", "description": "Time-series data as multiple series." }, "granularity": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "Granularity of the data." } }, "required": [ "series", "granularity" ], "type": "object", "additionalProperties": false }, "AttributionDataCostBreakdownItemDTO": { "description": "Attribution data cost breakdown item.", "properties": { "attribution_value": { "type": "string", "description": "Attribution value (e.g., agent name or workflow name)." }, "total_cost": { "type": "string", "description": "Total cost for this attribution value." }, "input_tokens": { "type": "number", "format": "double", "description": "Input tokens used." }, "output_tokens": { "type": "number", "format": "double", "description": "Output tokens used." }, "cache_creation_input_tokens": { "type": "number", "format": "double", "nullable": true, "description": "Cache-creation input tokens; null = provider did not report." }, "cache_read_input_tokens": { "type": "number", "format": "double", "nullable": true, "description": "Cache-read input tokens; null = provider did not report." }, "reasoning_tokens": { "type": "number", "format": "double", "nullable": true, "description": "Reasoning tokens; null = not reported." }, "input_cost": { "type": "string", "description": "Input cost (USD, decimal string)." }, "output_cost": { "type": "string", "description": "Output cost (USD, decimal string)." }, "cache_creation_cost": { "type": "string", "nullable": true, "description": "Cache-creation cost (USD string); null = not reported." }, "cache_read_cost": { "type": "string", "nullable": true, "description": "Cache-read cost (USD string); null = not reported." }, "reasoning_cost": { "type": "string", "nullable": true, "description": "Reasoning cost (USD string); null = not reported." }, "event_count": { "type": "number", "format": "double", "description": "Number of events." }, "percent_of_total": { "type": "number", "format": "double", "description": "Percentage of the total cost within this query scope (date range plus any\nfilter_key/filter_value filter). Values across items sum to 100." } }, "required": [ "attribution_value", "total_cost", "input_tokens", "output_tokens", "cache_creation_input_tokens", "cache_read_input_tokens", "reasoning_tokens", "input_cost", "output_cost", "cache_creation_cost", "cache_read_cost", "reasoning_cost", "event_count", "percent_of_total" ], "type": "object", "additionalProperties": false }, "AttributionDataCostBreakdownResponseDTO": { "description": "Attribution data cost breakdown response.", "properties": { "items": { "items": { "$ref": "#/components/schemas/AttributionDataCostBreakdownItemDTO" }, "type": "array", "description": "Cost breakdown items." }, "total_cost": { "type": "string", "description": "Total cost across all items." } }, "required": [ "items", "total_cost" ], "type": "object", "additionalProperties": false }, "AttributionDataValuesResponseDTO": { "description": "Attribution data values response (list of unique values).", "properties": { "values": { "items": { "type": "string" }, "type": "array", "description": "Unique attribution values." } }, "required": [ "values" ], "type": "object", "additionalProperties": false }, "PublicAttributionTimeSeriesPointDTO": { "description": "Public attribution time-series data point.", "properties": { "date": { "type": "string", "description": "Date of the time bucket (ISO 8601)." }, "total_cost": { "type": "string", "description": "Total cost for this time bucket." }, "event_count": { "type": "number", "format": "double", "description": "Number of events in this time bucket." } }, "required": [ "date", "total_cost", "event_count" ], "type": "object", "additionalProperties": false }, "PublicAttributionTimeSeriesItemDTO": { "description": "Public attribution time-series item (one series line).", "properties": { "key": { "type": "string", "description": "Dimension value key." }, "label": { "type": "string", "description": "Display label for this series." }, "data_points": { "items": { "$ref": "#/components/schemas/PublicAttributionTimeSeriesPointDTO" }, "type": "array", "description": "Time-bucketed data points." } }, "required": [ "key", "label", "data_points" ], "type": "object", "additionalProperties": false }, "PublicAttributionTimeSeriesResponseDTO": { "description": "Public attribution time-series response.", "properties": { "series": { "items": { "$ref": "#/components/schemas/PublicAttributionTimeSeriesItemDTO" }, "type": "array", "description": "Array of series (top 5 + Other)." }, "granularity": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "Adaptive granularity based on date range." } }, "required": [ "series", "granularity" ], "type": "object", "additionalProperties": false }, "PublicAttributionDimensionKeysResponseDTO": { "description": "Public attribution dimension keys response.", "properties": { "keys": { "items": { "type": "string" }, "type": "array", "description": "Distinct metadata dimension keys." } }, "required": [ "keys" ], "type": "object", "additionalProperties": false }, "AttributionDataSessionCostBreakdownItemDTO": { "description": "Per-session cost totals for one session.", "properties": { "session_id": { "type": "string", "description": "The session_id value shared by this session's usage events." }, "session_type": { "type": "string", "description": "Freeform session category from the session_type event field (e.g.,\n\"support-agent\", \"batch-summarizer\"); \"unknown\" when the events carry\nno session_type." }, "total_cost": { "type": "string", "description": "Total cost for the session (USD, decimal string)." }, "event_count": { "type": "number", "format": "double", "description": "Number of usage events in the session." } }, "required": [ "session_id", "session_type", "total_cost", "event_count" ], "type": "object", "additionalProperties": false }, "AttributionDataSessionCostBreakdownResponseDTO": { "description": "Session cost breakdown response (one page of sessions plus a page-scoped summary).", "properties": { "sessions": { "items": { "$ref": "#/components/schemas/AttributionDataSessionCostBreakdownItemDTO" }, "type": "array", "description": "Sessions in this page, ordered by total cost descending." }, "summary": { "properties": { "avg_cost_per_session": { "type": "string", "description": "Average total_cost across the sessions in this response (USD, decimal\nstring)." }, "total_sessions": { "type": "number", "format": "double", "description": "Number of sessions in this response; always equals the length of the\nsessions array, never a range-wide total. Page until fewer than limit\nsessions are returned." } }, "required": [ "avg_cost_per_session", "total_sessions" ], "type": "object", "description": "Aggregates over the sessions returned in this response only (after\nlimit/offset), not over the full date range." } }, "required": [ "sessions", "summary" ], "type": "object", "additionalProperties": false }, "AttributionDataSessionTypeSegmentDTO": { "description": "Aggregated cost metrics for one session_type value.", "properties": { "session_type": { "type": "string", "description": "Session type label being aggregated (e.g., \"singleplayer\", \"multiplayer\")." }, "session_count": { "type": "number", "format": "double", "description": "Number of sessions with this session type in the date range." }, "total_cost": { "type": "string", "description": "Total cost across all sessions of this type (USD, decimal string)." }, "avg_cost_per_session": { "type": "string", "description": "Average cost per session for this type (USD, decimal string)." }, "total_event_count": { "type": "number", "format": "double", "description": "Total usage events across all sessions of this type." } }, "required": [ "session_type", "session_count", "total_cost", "avg_cost_per_session", "total_event_count" ], "type": "object", "additionalProperties": false }, "AttributionDataSessionTypeComparisonResponseDTO": { "description": "Singleplayer vs multiplayer cost comparison.", "properties": { "segments": { "items": { "$ref": "#/components/schemas/AttributionDataSessionTypeSegmentDTO" }, "type": "array", "description": "One segment per session_type value found in the date range. Events\nwithout a session_type metadata value are excluded from this comparison." }, "cost_efficiency_ratio": { "type": "number", "format": "double", "nullable": true, "description": "Weighted average cost per session of the non-\"singleplayer\" segments\ndivided by the \"singleplayer\" segment's average cost per session. Values\nbelow 1 mean those sessions cost less on average. Null when the range\nlacks a \"singleplayer\" segment, lacks any other segment, or the\n\"singleplayer\" average cost per session is zero." }, "savings_percent": { "type": "number", "format": "double", "nullable": true, "description": "Per-session savings relative to the \"singleplayer\" baseline, computed as\n(1 - cost_efficiency_ratio) * 100. Null under the same conditions as\ncost_efficiency_ratio." } }, "required": [ "segments", "cost_efficiency_ratio", "savings_percent" ], "type": "object", "additionalProperties": false }, "AttributionDataSessionDetailFeatureDTO": { "description": "Per-feature cost slice within one session.", "properties": { "feature": { "type": "string", "description": "Feature name from the session's usage events; events without a feature\nare grouped under \"unknown\"." }, "total_cost": { "type": "string", "description": "Total cost for this feature within the session (USD, decimal string)." }, "event_count": { "type": "number", "format": "double", "description": "Number of usage events for this feature within the session." } }, "required": [ "feature", "total_cost", "event_count" ], "type": "object", "additionalProperties": false }, "AttributionDataSessionDetailResponseDTO": { "description": "Detail view of one session with its per-feature cost breakdown.", "properties": { "session_id": { "type": "string", "description": "The session_id value shared by this session's usage events." }, "session_type": { "type": "string", "description": "Freeform session category from the session_type event field; \"unknown\"\nwhen the events carry no session_type." }, "total_cost": { "type": "string", "description": "Total cost for the session (USD, decimal string)." }, "features": { "items": { "$ref": "#/components/schemas/AttributionDataSessionDetailFeatureDTO" }, "type": "array", "description": "Per-feature cost breakdown within the session, ordered by cost descending." } }, "required": [ "session_id", "session_type", "total_cost", "features" ], "type": "object", "additionalProperties": false }, "AttributionDataSessionTreeNodeDTO": { "description": "One span node in a session's call tree.", "properties": { "span_id": { "type": "string", "description": "This span's id (the span_id value on its usage events)." }, "parent_span_id": { "type": "string", "nullable": true, "description": "The caller's span id (the tree edge); null on a true root span." }, "name": { "type": "string", "nullable": true, "description": "Span label from the span_name event field; null when never provided." }, "kind": { "type": "string", "nullable": true, "description": "Span kind from the span_kind event field (agent, tool, llm, retrieval,\ntask); null when never provided." }, "agent_id": { "type": "string", "nullable": true, "description": "The agent_id attribution label on this span's events; null when absent." }, "own_cost": { "type": "string", "description": "Cost of this span's own events (USD, decimal string)." }, "subtree_cost": { "type": "string", "description": "Cost of this span plus every descendant span (USD, decimal string).\nIncludes descendants beyond the depth cap even though they are not\nmaterialized as children." }, "event_count": { "type": "number", "format": "double", "description": "Number of this span's own usage events." }, "depth": { "type": "number", "format": "double", "description": "Depth in the materialized tree; roots are depth 0." }, "orphaned": { "type": "boolean", "description": "True when this span's parent id does not exist in the session, so the\nspan was promoted to a root instead of being dropped." }, "cycle": { "type": "boolean", "description": "Present and true when a parent-pointer cycle was detected here: either\nthis span was promoted to a root to break the cycle, or its child edge\nback into the cycle was pruned. Only manual span_id misuse can produce\ncycles; SDK-generated span ids cannot." }, "depth_capped": { "type": "boolean", "description": "Present and true when descendants deeper than the 32-level cap were cut\nfrom this node; their cost is still included in subtree_cost." }, "children": { "items": { "$ref": "#/components/schemas/AttributionDataSessionTreeNodeDTO" }, "type": "array", "description": "Child spans, ordered by subtree_cost descending." } }, "required": [ "span_id", "parent_span_id", "name", "kind", "agent_id", "own_cost", "subtree_cost", "event_count", "depth", "orphaned", "children" ], "type": "object", "additionalProperties": false }, "AttributionDataSessionTreeUntracedDTO": { "description": "The session's untraced cost bucket: events that carry the session_id but\nno span_id.", "properties": { "total_cost": { "type": "string", "description": "Total cost of the session's span-less events (USD, decimal string)." }, "event_count": { "type": "number", "format": "double", "description": "Number of the session's span-less usage events." } }, "required": [ "total_cost", "event_count" ], "type": "object", "additionalProperties": false }, "AttributionDataSessionTreeResponseDTO": { "description": "Call-tree view of one session.", "properties": { "session_id": { "type": "string", "description": "The session_id value shared by this session's usage events." }, "roots": { "items": { "$ref": "#/components/schemas/AttributionDataSessionTreeNodeDTO" }, "type": "array", "description": "Root spans of the session's call tree, ordered by subtree_cost\ndescending. Spans whose parent id is missing from the session appear\nhere flagged orphaned." }, "untraced": { "$ref": "#/components/schemas/AttributionDataSessionTreeUntracedDTO", "description": "Cost of the session's events that carry no span_id." } }, "required": [ "session_id", "roots", "untraced" ], "type": "object", "additionalProperties": false }, "AttributionDataOutcomeItemDTO": { "description": "Cost and unit counts for one declared outcome value.", "properties": { "outcome": { "type": "string", "description": "The declared outcome value (the span's outcome option, e.g., \"ticket_resolved\")." }, "completed_count": { "type": "number", "format": "double", "description": "Distinct units that completed inside the date range. Retried units\n(same unit_key across attempts) count once; a unit counts as completed\nwhen any of its attempts completed." }, "completed_cost": { "type": "string", "description": "Total cost of the completed units (USD, decimal string). Sums every\nattempt's full call-subtree cost, including failed attempts of a unit\nthat later completed. A unit's cost may predate the date range; the\nrange filters on when the unit RESOLVED, not on when it spent." }, "cost_per_completed_unit": { "type": "string", "nullable": true, "description": "completed_cost divided by completed_count (USD, decimal string). Null\nwhen completed_count is 0; a real \"0\" would mean completed units were\nfree, which is a different fact than \"nothing completed\"." }, "failed_count": { "type": "number", "format": "double", "description": "Distinct units whose every attempt failed inside the date range." }, "failed_cost": { "type": "string", "description": "Total cost of the failed units (USD, decimal string)." }, "unresolved_count": { "type": "number", "format": "double", "description": "Units that declared this outcome but never reported completion or\nfailure (for example, the process died) and have been inactive longer\nthan unresolved_after_hours. Units still inside that inactivity window\nare treated as running and are not counted anywhere." }, "unresolved_cost": { "type": "string", "description": "Total cost of the unresolved units (USD, decimal string)." }, "retried_unit_count": { "type": "number", "format": "double", "description": "Units with more than one terminal (completion or failure) event under\nthe same unit_key. An attempt that died without emitting a terminal\nevent (process death) contributes its cost but does not increment this\ncounter; it surfaces through the unresolved bucket instead." } }, "required": [ "outcome", "completed_count", "completed_cost", "cost_per_completed_unit", "failed_count", "failed_cost", "unresolved_count", "unresolved_cost", "retried_unit_count" ], "type": "object", "additionalProperties": false }, "AttributionDataOutcomeBreakdownResponseDTO": { "description": "Cost-per-outcome response.", "properties": { "items": { "items": { "$ref": "#/components/schemas/AttributionDataOutcomeItemDTO" }, "type": "array", "description": "One item per outcome value, ordered by total unit cost descending." }, "total_outcome_count": { "type": "number", "format": "double", "description": "Number of distinct outcome values in the range; equals items.length." } }, "required": [ "items", "total_outcome_count" ], "type": "object", "additionalProperties": false }, "UsageEventResponse": { "description": "Response for usage event ingestion (snake_case wire format).", "properties": { "event_id": { "type": "string", "description": "Internal event ID (UUID) assigned by the system. Deterministic per\nidempotency_key, so retries of the same event return the same value." }, "status": { "type": "string", "enum": [ "accepted", "accepted_flagged" ], "description": "Acceptance status. 'accepted_flagged' means the event was accepted and\nwill be processed but needs attention; flag_reason states the cause." }, "message": { "type": "string", "description": "Human-readable message." }, "flag_reason": { "type": "string", "description": "Reason for flagging (if status is accepted_flagged)." } }, "required": [ "event_id", "status", "message" ], "type": "object", "additionalProperties": false }, "UsageEventExperiment": { "description": "A/B experiment attribution for a usage event. Both fields are required when\n`experiment` is present: an event inside an experiment always belongs to a\nspecific variant, so the pair is meaningless apart.", "properties": { "id": { "type": "string", "description": "The experiment identifier.", "example": "checkout-copy-v3", "minLength": 1, "maxLength": 255 }, "variant": { "type": "string", "description": "The variant this event belongs to within the experiment.", "example": "treatment", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "variant" ], "type": "object", "additionalProperties": false }, "Record_string.unknown_": { "properties": {}, "additionalProperties": {}, "type": "object", "description": "A map of string keys to arbitrary JSON values." }, "UsageEventRequest": { "description": "A single AI usage event to record for cost calculation (snake_case wire format).", "properties": { "idempotency_key": { "type": "string", "description": "A client-generated UUID you supply to make ingestion idempotent. Retries\nare deduplicated by this key (per organization and API-key environment):\nresubmitting the same idempotency_key returns the same event_id and is\nnever double counted. You must generate the UUID yourself; reusing a key\nfor a genuinely different event causes that event to be silently dropped\nas a duplicate.", "example": "3f9a2b1c-8d7e-4f6a-9b2c-1a2b3c4d5e6f", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" }, "model": { "type": "string", "description": "Model name/slug for the call being recorded.", "example": "gpt-4o", "minLength": 1, "maxLength": 255 }, "input_tokens": { "type": "number", "format": "double", "description": "Number of input tokens used.", "minimum": 0 }, "output_tokens": { "type": "number", "format": "double", "description": "Number of output tokens generated.", "minimum": 0 }, "event_invoked_at": { "type": "string", "description": "When the event occurred (ISO 8601). This is the event's own occurrence\ntime and MAY be backdated to record historical usage (backfill). It is\nindependent of the X-Timestamp request-signing header, which must always\nbe current. Events whose occurrence time is more than 24 hours old are\naccepted but flagged (status \"accepted_flagged\"); see the endpoint\ndescription." }, "cache_creation_input_tokens": { "type": "number", "format": "double", "description": "Cache creation input tokens (Anthropic prompt caching)." }, "cache_read_input_tokens": { "type": "number", "format": "double", "description": "Cache read input tokens (Anthropic prompt caching)." }, "reasoning_tokens": { "type": "number", "format": "double", "description": "Reasoning tokens (OpenAI o-series, reported under completion_tokens_details.reasoning_tokens)." }, "units": { "$ref": "#/components/schemas/Record_string.number_", "description": "Non-token usage units (e.g., { characters: 500 } or { generations: 1 })." }, "cost_override": { "type": "number", "format": "double", "description": "A pre-computed cost in USD that OVERRIDES the normal rate-card calculation\nfor this event. Supply it only when you already know the exact price and do\nnot want it derived from the model, token counts, and your rate card: for\nexample a negotiated rate not in your rate card, or a provider that prices\nin units you compute yourself. Omit it for the normal path, where Bear\nLumen computes the cost from your rate card. When present, the token and\nunit fields are still recorded for volume analytics but do not affect the\nstored cost.", "minimum": 0 }, "user_id": { "type": "string", "description": "Optional identifier for the end user of your product (your own user ID).\nStored as the end user's externalId for per-user cost attribution; the\nend-user cost endpoints return it alongside the Bear Lumen endUserId." }, "agent_id": { "type": "string", "description": "AI agent identifier for cost attribution." }, "workflow_id": { "type": "string", "description": "Workflow identifier for cost attribution." }, "feature": { "type": "string", "description": "Feature/capability used (e.g., 'chat', 'tts', 'image-gen', 'embeddings')." }, "provider": { "type": "string", "description": "AI provider identifier (e.g., 'openai', 'anthropic', 'aws-bedrock', 'google')." }, "experiment": { "$ref": "#/components/schemas/UsageEventExperiment", "description": "A/B experiment attribution for this event. Omit it when the call is not\npart of an experiment. When present, both id and variant are required." }, "session_id": { "type": "string", "description": "Identifier of the session (a run or trace) this event belongs to. All\nevents sharing a session_id are grouped into one session for cost\nattribution and call-tree read-back. Required whenever span or outcome\nfields are supplied.", "example": "0d9a1f4e-3c2b-4a7d-9e6f-1b5c8d2a7e40", "maxLength": 128 }, "session_type": { "type": "string", "description": "Freeform category for the session, constant across every event in it.\nUse it to compare cost across kinds of runs, for example \"support-chat\"\nversus \"batch-summarize\".", "example": "support-chat", "maxLength": 128 }, "span_id": { "type": "string", "description": "Identifier of the span (the call-tree node) this event executed under, as\nexactly 16 lowercase hex characters. Requires session_id.", "example": "a3f81b2c9d4e5f60", "pattern": "^[0-9a-f]{16}$" }, "parent_span_id": { "type": "string", "description": "Span identifier of the caller, as exactly 16 lowercase hex characters.\nForms the parent edge in the session's call tree. Requires span_id and\nmust differ from it.", "example": "17c4d9e2a5b3f708", "pattern": "^[0-9a-f]{16}$" }, "span_name": { "type": "string", "description": "Human-readable label for the span, returned as the node name when the\nsession's call tree is read back. Requires span_id.", "example": "research-subtask", "maxLength": 128 }, "span_kind": { "type": "string", "enum": [ "agent", "tool", "llm", "retrieval", "task" ], "description": "The kind of work the span represents. Enables cost roll-ups by span kind.\nRequires span_id.", "example": "agent" }, "outcome": { "type": "string", "description": "Declared outcome name of the unit of work this event contributes to, for\nexample \"ticket-resolved\". Stamped on every cost event inside an outcome\nspan and on its closing terminal event. Requires session_id.", "example": "ticket-resolved", "maxLength": 128 }, "outcome_status": { "type": "string", "enum": [ "completed", "failed" ], "description": "Resolution of the declared outcome. Send it only on the zero-cost\nterminal event that closes an outcome span; ordinary cost events omit it.\nRequires outcome.", "example": "completed" }, "unit_key": { "type": "string", "description": "Stable identity for a retryable unit of work, such as a job or request\nidentifier. Cost sums across attempts that share a unit_key while the\noutcome is counted once.", "example": "job-8412", "maxLength": 128 }, "metadata": { "$ref": "#/components/schemas/Record_string.unknown_", "description": "Optional additional metadata for attribution. If your organization defines\nrequired custom dimensions, those keys must be present in metadata or the\nevent is rejected with 400. Dimension values are validated against each\ndimension's type and maximum length." } }, "required": [ "idempotency_key", "model", "input_tokens", "output_tokens", "event_invoked_at" ], "type": "object", "additionalProperties": false }, "UsageEventBatchItemResult": { "description": "Per-event result in a batch response.", "properties": { "index": { "type": "number", "format": "double", "description": "Index of the event in the batch." }, "event_id": { "type": "string", "description": "Internal event ID (if accepted)." }, "status": { "type": "string", "enum": [ "accepted", "accepted_flagged", "rejected" ], "description": "Acceptance status. 'accepted_flagged' means accepted but needs attention\n(see flag causes on the endpoint description); 'rejected' means the event\nwas not recorded and the error field states why." }, "message": { "type": "string", "description": "Human-readable message." }, "error": { "type": "string", "description": "Error details (if rejected)." } }, "required": [ "index", "status", "message" ], "type": "object", "additionalProperties": false }, "UsageEventBatchResponse": { "description": "Response for batch usage event ingestion.", "properties": { "results": { "items": { "$ref": "#/components/schemas/UsageEventBatchItemResult" }, "type": "array", "description": "Per-event results." }, "accepted": { "type": "number", "format": "double", "description": "Total events accepted." }, "failed": { "type": "number", "format": "double", "description": "Total events rejected. Rejections can be caused by validation failure,\nplan event quota exhaustion, or an unexpected processing error; inspect\nresults[].error for the cause of each." } }, "required": [ "results", "accepted", "failed" ], "type": "object", "additionalProperties": false }, "UsageEventBatchRequest": { "description": "Request body for batch usage event ingestion.", "properties": { "events": { "items": { "$ref": "#/components/schemas/UsageEventRequest" }, "type": "array", "description": "Array of usage events to ingest (1 to 100 events per batch).", "minItems": 1, "maxItems": 100 } }, "required": [ "events" ], "type": "object", "additionalProperties": false, "example": { "events": [ { "idempotency_key": "3f9a2b1c-8d7e-4f6a-9b2c-1a2b3c4d5e6f", "model": "gpt-4o", "input_tokens": 1500, "output_tokens": 420, "event_invoked_at": "2026-01-15T10:30:00.000Z", "provider": "openai", "feature": "chat" }, { "idempotency_key": "7c1d4e2f-9a8b-4c3d-8e7f-6a5b4c3d2e1f", "model": "claude-3-5-sonnet", "input_tokens": 900, "output_tokens": 310, "event_invoked_at": "2026-01-15T10:31:00.000Z", "provider": "anthropic", "feature": "chat" } ] } } }, "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "API key authentication over HTTP Bearer.\n\nCreate a key in your Bear Lumen dashboard (app.bearlumen.com > Settings > API Keys) and send it on every request as `Authorization: Bearer YOUR_API_KEY`. In this reference, paste only the key; the `Bearer ` prefix is added automatically.\n\nKeys carry scopes that limit what they can access:\n- `usage:write`: send usage events (POST /usage-events, POST /usage-events/batch)\n- `usage:read`: query recorded usage events and aggregations\n- `costs:read`: read cost summaries, breakdowns, trends, attribution, and per-end-user costs\n- `revenue:read`: read margin and profitability analysis\n- `dimensions:read`: read custom dimension definitions\n\nEach read operation lists its required scope in its security requirements. The usage ingestion endpoints (POST /usage-events, POST /usage-events/batch) require the `usage:write` scope." }, "hmacSignature": { "type": "apiKey", "name": "X-Signature", "in": "header", "description": "HMAC request signing, required in addition to your API key on the usage ingestion endpoints (POST /usage-events and POST /usage-events/batch). Read endpoints do not use it.\n\nTo sign a request:\n1. Set `X-Timestamp` to the current Unix time in seconds.\n2. Build the payload string `{timestamp}.{body}`, where `body` is the raw JSON request body exactly as sent.\n3. Compute HMAC-SHA256 of that payload keyed with your API key, hex-encoded.\n4. Send `X-Signature: v1={hex digest}`.\n\nRequests whose timestamp is more than 5 minutes from server time are rejected. Missing or invalid signatures return 401 with a flat `{ \"error\": string, \"code\": string }` body (codes: `HMAC_MISSING_SIGNATURE`, `HMAC_MISSING_TIMESTAMP`, `HMAC_INVALID_SIGNATURE`)." } } }, "info": { "title": "Bear Lumen API", "version": "2025-10-18", "description": "The Bear Lumen API tracks AI provider usage, attributes cost by custom dimensions, and reports margin against your revenue. You send usage events as your application calls AI providers, then read cost, attribution, and margin data back.\n\nThe sections below cover the conventions that apply across every endpoint. Read them once, then refer to the individual operations for request and response shapes. Full guides and quickstarts live at https://docs.bearlumen.com.\n\n## Authentication\n\nEvery request authenticates with a Bearer API key. Create a key in your dashboard (app.bearlumen.com, under Settings then API Keys) and send it on every request:\n\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\nKeys are scoped, so a key can read cost data without being able to send usage events, and vice versa. See Permissions and scopes for the full list. Full scheme details, including the interactive console, appear in the Authentication panel of this reference.\n\n## Permissions and scopes\n\nEach API key carries one or more scopes. Every operation states the scope it needs in its security requirements, and a key without that scope receives 403.\n\n| Scope | Grants |\n| --- | --- |\n| `usage:write` | Send usage events (POST /usage-events, POST /usage-events/batch). |\n| `usage:read` | Query recorded usage events and aggregations. |\n| `costs:read` | Read cost summaries, breakdowns, trends, attribution, and per-end-user costs. |\n| `revenue:read` | Read margin and profitability analysis. |\n| `dimensions:read` | Read custom dimension definitions. |\n\n## Request signing (HMAC)\n\nThe usage ingestion endpoints (POST /usage-events and POST /usage-events/batch) require an HMAC signature in addition to your API key. Read endpoints do not.\n\nTo sign a request, set `X-Timestamp` to the current Unix time in seconds, build the payload string `{timestamp}.{body}` where `body` is the raw JSON request body exactly as sent, compute HMAC-SHA256 of that payload keyed with your API key, and send it hex-encoded as `X-Signature: v1={hex digest}`. Requests whose timestamp is more than 5 minutes from server time are rejected with 401.\n\n## Idempotency\n\nUsage-event retries are safe. Events are deduplicated by their `idempotency_key` within each organization and API key environment. Resubmitting an event with an `idempotency_key` the API has already accepted returns 202 with the same `event_id` and is never counted twice, so you can retry a failed or timed-out ingestion request without double counting.\n\nIngestion is accepted asynchronously. A 202 means the event passed validation and is queued for cost processing, not that processing has finished.\n\n## Errors\n\nEvery error, across all 4xx and 5xx responses, uses one envelope:\n\n```json\n{\n \"success\": false,\n \"error\": {\n \"code\": \"RATE_LIMIT_EXCEEDED\",\n \"message\": \"Human-readable summary of what went wrong.\",\n \"correlationId\": \"OLIVE-DINOSAUR-1b2fE4\",\n \"referenceCode\": \"OLIVE-DINOSAUR-1b2fE4\",\n \"details\": { \"retryable\": true }\n }\n}\n```\n\nBranch on `error.code` for programmatic handling rather than on the message text. `error.details.retryable` tells you whether repeating the same request may succeed. Quote `error.correlationId` (also returned as the `X-Correlation-ID` response header) when you contact support so we can trace the exact request. Every response also carries an `X-Request-ID` header.\n\nThe one exception: HMAC signature failures on the ingestion endpoints return a flat `{ \"error\": string, \"code\": string }` body instead of this envelope, with codes `HMAC_MISSING_SIGNATURE`, `HMAC_MISSING_TIMESTAMP`, or `HMAC_INVALID_SIGNATURE`.\n\n## Rate limits\n\nRequests are rate limited per API key. When you exceed the limit you receive 429 with code `RATE_LIMIT_EXCEEDED`. Every response reports the current window state in the standard `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` headers, and a 429 additionally includes `Retry-After` with the number of seconds to wait. Back off until the window resets rather than retrying immediately.\n\nA second, separate 429 class exists on the ingestion endpoints: when your plan's monthly event quota is exhausted, the single-event endpoint returns 429 with `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `Retry-After` headers (the batch endpoint instead rejects per item inside its 202 response). Quota 429s reset when your plan period renews, not on the rate-limit window.\n\n## Conventions\n\nThese conventions hold across every endpoint.\n\n### Dates and time ranges\n\nTimestamps are ISO 8601 in UTC. Most query endpoints accept a `start_date` and `end_date` window. Three exceptions: GET /cost-data/summary takes a `time_window` preset instead of explicit dates, GET /insights/summary names its window `start` and `end`, and the GET /usage/* endpoints currently name theirs `startDate` and `endDate`. Each operation lists its exact parameters. Keep ranges reasonable, since very wide windows return more data and take longer to compute.\n\n### Money and currency\n\nAll amounts are in US dollars. Fields whose name ends in `Cents` are integers in USD cents (for example `instrumentationGapCents`). Other amount fields are decimal strings in dollars (for example `marginAmount`). Each field states its unit in its own description, so read it before doing math.\n\n### Pagination\n\nList endpoints that can return large result sets accept `limit` and `offset`. Page by increasing `offset` in steps of `limit` until a page returns fewer rows than `limit`.\n\n### Field naming\n\nThe usage ingestion endpoints use snake_case field names (`idempotency_key`, `input_tokens`, `user_id`). The read APIs return camelCase field names. This split is intentional, so follow the casing shown in each operation.\n\n## Environments and versioning\n\nThe API base URL is `https://api.bearlumen.com/v1`. Each API key belongs to either a test or a live environment, and data does not cross between them, so you can integrate against test keys without touching live data. The `/v1` prefix is the API version. Any future incompatible version ships under a new prefix, so `/v1` keeps working.", "contact": { "name": "Bear Lumen", "email": "support@bearlumen.com" } }, "paths": { "/usage/events": { "get": { "operationId": "query-usage-events", "responses": { "200": { "description": "Usage events retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryUsageEventsResponseDTO" }, "example": { "events": [ { "event_timestamp": "2026-01-27T19:12:00.000Z", "event_type": "ai.inference", "id": "d7e6f5a4-9999-4b1c-8d2e-3f4a5b6c7d08", "metadata": { "feature": "chat", "provider": "google" }, "metric_name": "tokens", "quantity": 3122000 }, { "event_timestamp": "2026-01-22T08:53:00.000Z", "event_type": "ai.inference", "id": "d7e6f5a4-9999-4b1c-8d2e-3f4a5b6c7d06", "metadata": { "agent_id": "support-triage", "feature": "search", "provider": "openai" }, "metric_name": "tokens", "quantity": 6010000 }, { "event_timestamp": "2026-01-19T16:05:00.000Z", "event_type": "ai.inference", "id": "d7e6f5a4-9999-4b1c-8d2e-3f4a5b6c7d04", "metadata": { "feature": "summarize", "provider": "anthropic" }, "metric_name": "tokens", "quantity": 1626900 }, { "event_timestamp": "2026-01-15T10:30:00.000Z", "event_type": "ai.inference", "id": "d7e6f5a4-9999-4b1c-8d2e-3f4a5b6c7d07", "metadata": { "feature": "chat", "provider": "google" }, "metric_name": "tokens", "quantity": 3995000 }, { "event_timestamp": "2026-01-12T14:32:00.000Z", "event_type": "ai.inference", "id": "d7e6f5a4-9999-4b1c-8d2e-3f4a5b6c7d02", "metadata": { "feature": "chat", "provider": "openai" }, "metric_name": "tokens", "quantity": 2773300 } ], "limit": 5, "offset": 0, "total": 8 } } } }, "400": { "description": "Invalid request parameters. Check that start_date and end_date are valid ISO 8601 dates, start_date is strictly before end_date, the range does not exceed 90 days, and limit is a positive integer no greater than 1000.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage/events", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage/events", "method": "GET" } } } } }, "403": { "description": "Forbidden. The API key is missing the usage:read scope; create or update a key with that scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage/events", "method": "GET" } } } } }, "404": { "description": "Subscription not found or not accessible with this API key. Check the subscription_id value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Resource not found or not accessible with this API key. Check the identifier and try again.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Resource not found or not accessible with this API key. Check the identifier and try again.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage/events", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage/events", "method": "GET" } } } } } }, "description": "Get usage events\n\nRetrieves individual usage events recorded for the account your API key\nbelongs to, within a date range. Use it to confirm ingested events landed.\nSupports pagination and filtering by subscription and metric.\nEvents sent via POST /usage-events appear here with eventType `ai.inference`\nand metricName `tokens`; quantity is total tokens (input plus output).\n\n**Required Scope:** `usage:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get usage events", "tags": [ "Usage Tracking" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Start of the query range. ISO 8601 date or datetime (e.g. 2026-01-01 or 2026-01-01T00:00:00Z). Include an explicit UTC offset; date-only values are interpreted as UTC midnight. Must be strictly before end_date; the range may not exceed 90 days.", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of the query range. ISO 8601 date or datetime. Maximum range: 90 days.", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } }, { "description": "Optional: Filter by subscription ID.", "in": "query", "name": "subscription_id", "required": false, "schema": { "type": "string" } }, { "description": "Optional: Filter by metric name. Metric names are stored lowercase and matched exactly; pass lowercase values (e.g. tokens).", "in": "query", "name": "metric_name", "required": false, "schema": { "type": "string" } }, { "description": "Optional: Number of events to return (default: 100, max: 1000, must be a positive integer).", "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Optional: Pagination offset (default: 0, must be zero or a positive integer).", "in": "query", "name": "offset", "required": false, "schema": { "format": "int32", "type": "integer" } } ], "x-required-scopes": [ "usage:read" ] } }, "/usage/aggregation": { "get": { "operationId": "query-usage-aggregation", "responses": { "200": { "description": "Usage aggregation retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryUsageAggregationResponseDTO" }, "example": { "aggregations": [ { "event_count": 8, "first_event_at": "2026-01-05T09:14:00.000Z", "last_event_at": "2026-01-27T19:12:00.000Z", "metric_name": "tokens", "total_quantity": 31226000 } ], "period_end": "2026-01-31T23:59:59.000Z", "period_start": "2026-01-01T00:00:00.000Z", "total_events": 8 } } } }, "400": { "description": "Invalid request parameters. Check that start_date and end_date are valid ISO 8601 dates, start_date is strictly before end_date, the range does not exceed 365 days, and metric_names lists at most 50 names.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage/aggregation", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage/aggregation", "method": "GET" } } } } }, "403": { "description": "Forbidden. The API key is missing the usage:read scope; create or update a key with that scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage/aggregation", "method": "GET" } } } } }, "404": { "description": "Subscription not found or not accessible with this API key. Check the subscription_id value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Resource not found or not accessible with this API key. Check the identifier and try again.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Resource not found or not accessible with this API key. Check the identifier and try again.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage/aggregation", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage/aggregation", "method": "GET" } } } } } }, "description": "Get usage aggregation\n\nReturns aggregated usage quantities by metric (total quantity, event\ncount, first and last event timestamps) for volume reporting. This\nendpoint returns no cost figures; for dollar amounts use GET\n/cost-data/summary or the other cost-data endpoints.\nData sent via POST /usage-events aggregates under metricName `tokens`.\n\n**Required Scope:** `usage:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get usage aggregation", "tags": [ "Usage Tracking" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Start of the aggregation range. ISO 8601 date or datetime (e.g. 2026-01-01 or 2026-01-01T00:00:00Z). Include an explicit UTC offset; date-only values are interpreted as UTC midnight. Must be strictly before end_date; the range may not exceed 365 days.", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of the aggregation range. ISO 8601 date or datetime. Maximum range: 365 days.", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } }, { "description": "Optional: Filter by subscription ID.", "in": "query", "name": "subscription_id", "required": false, "schema": { "type": "string" } }, { "description": "Optional: Comma-separated list of metric names to include (max 50). Metric names are stored lowercase and matched exactly; pass lowercase values (e.g. tokens).", "in": "query", "name": "metric_names", "required": false, "schema": { "type": "string" } } ], "x-required-scopes": [ "usage:read" ] } }, "/usage/summary": { "get": { "operationId": "query-usage-summary", "responses": { "200": { "description": "Usage summary retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryUsageSummaryResponseDTO" }, "example": { "metrics": [ { "event_count": 8, "metric_name": "tokens", "total_quantity": 31226000 } ], "period_end": "2026-01-31T23:59:59.000Z", "period_start": "2026-01-01T00:00:00.000Z", "total_events": 8, "user_id": "4f2a9c81-7d3e-4b6a-8c1f-5e9d2b7a3c14" } } } }, "400": { "description": "Invalid request parameters. Check that start_date and end_date are valid ISO 8601 dates and start_date is strictly before end_date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage/summary", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage/summary", "method": "GET" } } } } }, "403": { "description": "Forbidden. The API key is missing the usage:read scope; create or update a key with that scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage/summary", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage/summary", "method": "GET" } } } } } }, "description": "Get usage summary\n\nReturns a high-level usage summary for a period: total event count plus\nper-metric totals. For cost totals, use GET /cost-data/summary.\n\n**Required Scope:** `usage:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get usage summary", "tags": [ "Usage Tracking" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Start of the summary period. ISO 8601 date or datetime (e.g. 2026-01-01 or 2026-01-01T00:00:00Z). Include an explicit UTC offset; date-only values are interpreted as UTC midnight. Must be strictly before end_date.", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of the summary period. ISO 8601 date or datetime. Must be strictly after start_date.", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "usage:read" ] } }, "/rate-cards/estimation-table": { "get": { "operationId": "getRateEstimationTable", "responses": { "200": { "description": "Rate estimation table retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateEstimationTableResponseDTO" }, "example": { "items": [ { "cache_creation_cost_per_million": "3.75", "cache_read_cost_per_million": "0.3", "input_cost_per_million": "3", "model_slug": "claude-sonnet-4-5", "output_cost_per_million": "15", "reasoning_cost_per_million": "15" }, { "cache_creation_cost_per_million": "3.125", "cache_read_cost_per_million": "0.25", "input_cost_per_million": "2.5", "model_slug": "gpt-4o", "output_cost_per_million": "10", "reasoning_cost_per_million": "10" }, { "cache_creation_cost_per_million": "0.15", "cache_read_cost_per_million": "0.012", "input_cost_per_million": "0.12", "model_slug": "gpt-4o-mini", "output_cost_per_million": "0.48", "reasoning_cost_per_million": "0.48" }, { "cache_creation_cost_per_million": "0.7375", "cache_read_cost_per_million": "0.059", "input_cost_per_million": "0.59", "model_slug": "llama-3.3-70b-versatile", "output_cost_per_million": "0.79", "reasoning_cost_per_million": "0.79" }, { "cache_creation_cost_per_million": "1.1", "cache_read_cost_per_million": "0.088", "input_cost_per_million": "0.88", "model_slug": "meta-llama/Llama-3.3-70B-Instruct", "output_cost_per_million": "0.88", "reasoning_cost_per_million": "0.88" }, { "cache_creation_cost_per_million": "2.5", "cache_read_cost_per_million": "0.2", "input_cost_per_million": "2", "model_slug": "mistral-large", "output_cost_per_million": "6", "reasoning_cost_per_million": "6" }, { "cache_creation_cost_per_million": "0.25", "cache_read_cost_per_million": "0.02", "input_cost_per_million": "0.2", "model_slug": "mistral-small", "output_cost_per_million": "0.6", "reasoning_cost_per_million": "0.6" } ] } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/rate-cards/estimation-table", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update an API key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/rate-cards/estimation-table", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/rate-cards/estimation-table", "method": "GET" } } } } } }, "description": "Get the rate estimation table\n\nReturns your organization's effective per-model rates in USD per million\ntokens, for client-side budget estimation; the server-side ledger is the\nrecord. The Bear Lumen SDKs refresh their local price table from this\nendpoint at startup and use it to estimate span spend before each call,\nso budget caps can stop a runaway loop without waiting for the ledger.\nTreat the values as estimates only: the ledger prices each event with the\nrates in force at the event's own timestamp, so the two can diverge when\nrates change mid-run.\n\nRates reflect your organization: when custom rates are agreed with Bear\nLumen for a model, those replace the standard rates here. Cache and\nreasoning rates are already resolved to the same derived values the\nledger applies, so you can multiply token counts by these rates directly.\nModels priced per unit rather than per token are not listed.\n\nRefresh once at process start (or at most hourly); rates change rarely.\n\n**Required Scope:** `costs:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get the rate estimation table", "tags": [ "Rate Cards API" ], "security": [ { "apiKey": [] } ], "parameters": [], "x-required-scopes": [ "costs:read" ] } }, "/ping": { "get": { "operationId": "ping", "responses": { "200": { "description": "API key is valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponseDTO" }, "example": { "ok": true, "organization_id": "b7e6a3f2-4c1d-4e8a-9b5f-2d7c8e1a6f43" } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/ping", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/ping", "method": "GET" } } } } } }, "description": "Ping the API to verify connectivity and API key validity.\n\nReturns the organization ID associated with the API key.\nUse this to verify your API key and connectivity before sending events.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "API connectivity check", "tags": [ "Connectivity" ], "security": [ { "apiKey": [] } ], "parameters": [] } }, "/margin-data/summary": { "get": { "operationId": "getMarginDataSummary", "responses": { "200": { "description": "Margin summary retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarginDataSummaryResponseDTO" }, "example": { "summary": { "cost_record_count": 13, "margin_amount": "5138.8199999999999991", "margin_percent": 42.5, "profitability_category": "profitable", "revenue_record_count": 5, "total_cost": "6952.7", "total_revenue": "12091.5199999999999991", "unattributed_cost": "431.06", "unattributed_revenue": "1240.12" }, "warnings": [ { "count": 1, "message": "1 revenue record(s) without customer attribution", "type": "unattributed_revenue" }, { "count": 1, "message": "1 cost record(s) without customer attribution", "type": "unattributed_cost" }, { "count": 0, "message": "No active Stripe revenue connection. Revenue totals reflect no connected source, not necessarily zero revenue.", "type": "revenue_not_connected" } ] } } } }, "400": { "description": "Invalid query parameters. Check that start_date and end_date are valid ISO 8601 dates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/margin-data/summary", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/margin-data/summary", "method": "GET" } } } } }, "403": { "description": "API key lacks the revenue:read scope. Use a key that includes the revenue:read scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/margin-data/summary", "method": "GET" } } } } }, "422": { "description": "Date range exceeds 12 months. Narrow start_date and end_date to a span of 12 months or less.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNPROCESSABLE_ENTITY", "message": "Date range exceeds 12 months. Narrow start_date and end_date to a span of 12 months or less.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Date range exceeds 12 months. Narrow start_date and end_date to a span of 12 months or less.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/margin-data/summary", "method": "GET" } } } } }, "429": { "description": "Rate limit exceeded. Reduce request frequency and retry after the interval indicated in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/margin-data/summary", "method": "GET" } } } } } }, "description": "Get margin summary\n\nReturns total revenue, cost, and margin for the organization with warnings\nabout unattributed data and profitability classification.\n\nMargin requires revenue data from your connected Stripe account; connect\nit in your dashboard under Settings then Integrations. Note that a\nnot-yet-connected account and a genuine zero-revenue period both return\n\"0\", so verify the connection before interpreting zeros. If no\nrevenue has been synced for the period, revenue fields return \"0\",\nmargin_percent is null (division by zero is undefined), and\nprofitability_category reflects cost-only activity (unprofitable when\ncost > 0, break-even when there is no activity).\n\nRevenue is recognized on an accrual basis: each revenue record's amount is\nattributed across its billing period. Costs are attributed to the time the\nusage event occurred.\n\n**Required Scope:** `revenue:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get margin summary", "tags": [ "Margin Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Start of date range (ISO 8601, inclusive).", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "revenue:read" ] } }, "/margin-data/by-end-user": { "get": { "operationId": "getMarginDataByEndUser", "responses": { "200": { "description": "Margin breakdown retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarginDataByEndUserResponseDTO" }, "example": { "end_users": [ { "cost": "894.37", "end_user_id": "eb77aa11-0003-7777-9a1b-2c3d4e5f6a03", "end_user_name": "Cobalt Labs", "margin_amount": "-228.249999999999999", "margin_percent": -34.27, "profitability_category": "unprofitable", "revenue": "666.120000000000001" }, { "cost": "2192.15", "end_user_id": "eb77aa11-0002-7777-9a1b-2c3d4e5f6a02", "end_user_name": "Beacon Analytics", "margin_amount": "357.8100000000000001", "margin_percent": 14.03, "profitability_category": "break-even", "revenue": "2549.9600000000000001" }, { "cost": "3435.12", "end_user_id": "eb77aa11-0001-7777-9a1b-2c3d4e5f6a01", "end_user_name": "Aurora Systems", "margin_amount": "4200.1999999999999975", "margin_percent": 55.01, "profitability_category": "profitable", "revenue": "7635.3199999999999975" } ], "org_total": { "cost_record_count": 13, "margin_amount": "5138.8199999999999991", "margin_percent": 42.5, "profitability_category": "profitable", "revenue_record_count": 5, "total_cost": "6952.7", "total_revenue": "12091.5199999999999991", "unattributed_cost": "431.06", "unattributed_revenue": "1240.12" }, "warnings": [ { "count": 1, "message": "1 revenue record(s) without customer attribution", "type": "unattributed_revenue" }, { "count": 1, "message": "1 cost record(s) without customer attribution", "type": "unattributed_cost" }, { "count": 0, "message": "No active Stripe revenue connection. Revenue totals reflect no connected source, not necessarily zero revenue.", "type": "revenue_not_connected" } ] } } } }, "400": { "description": "Invalid query parameters. Check that start_date and end_date are valid ISO 8601 dates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/margin-data/by-end-user", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/margin-data/by-end-user", "method": "GET" } } } } }, "403": { "description": "API key lacks the revenue:read scope. Use a key that includes the revenue:read scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/margin-data/by-end-user", "method": "GET" } } } } }, "422": { "description": "Date range exceeds 12 months. Narrow start_date and end_date to a span of 12 months or less.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNPROCESSABLE_ENTITY", "message": "Date range exceeds 12 months. Narrow start_date and end_date to a span of 12 months or less.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Date range exceeds 12 months. Narrow start_date and end_date to a span of 12 months or less.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/margin-data/by-end-user", "method": "GET" } } } } }, "429": { "description": "Rate limit exceeded. Reduce request frequency and retry after the interval indicated in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/margin-data/by-end-user", "method": "GET" } } } } } }, "description": "Get per-end-user margin breakdown\n\nReturns margin data for each of your end users (the customers you\nattribute usage and revenue to), sorted by profitability with the least\nprofitable first so unprofitable end users surface at the top.\n\nMargin requires revenue data from your connected Stripe account; connect\nit in your dashboard under Settings then Integrations. Note that a\nnot-yet-connected account and a genuine zero-revenue period both return\n\"0\", so verify the connection before interpreting zeros. If no\nrevenue has been synced for the period, revenue fields return \"0\",\nmargin_percent is null (division by zero is undefined), and\nprofitability_category reflects cost-only activity (unprofitable when\ncost > 0, break-even when there is no activity).\n\nRevenue is recognized on an accrual basis: each revenue record's amount is\nattributed across its billing period. Costs are attributed to the time the\nusage event occurred.\n\n**Required Scope:** `revenue:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get margin by end user", "tags": [ "Margin Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Start of date range (ISO 8601, inclusive).", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "revenue:read" ] } }, "/margin-data/trend": { "get": { "operationId": "getMarginDataTrend", "responses": { "200": { "description": "Margin trend retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarginDataTrendResponseDTO" }, "example": { "data_points": [ { "cost": "0", "date": "2026-05-15T00:00:00.000Z", "margin_amount": "246.3006451612903225", "margin_percent": 100, "revenue": "246.3006451612903225" }, { "cost": "522.3", "date": "2026-05-16T00:00:00.000Z", "margin_amount": "-275.9993548387096775", "margin_percent": -112.06, "revenue": "246.3006451612903225" }, { "cost": "0", "date": "2026-05-17T00:00:00.000Z", "margin_amount": "246.3006451612903225", "margin_percent": 100, "revenue": "246.3006451612903225" }, { "cost": "336.48", "date": "2026-05-18T00:00:00.000Z", "margin_amount": "-90.1793548387096775", "margin_percent": -36.61, "revenue": "246.3006451612903225" }, { "cost": "0", "date": "2026-05-19T00:00:00.000Z", "margin_amount": "246.3006451612903225", "margin_percent": 100, "revenue": "246.3006451612903225" }, { "cost": "241.06", "date": "2026-05-20T00:00:00.000Z", "margin_amount": "5.2406451612903225", "margin_percent": 2.13, "revenue": "246.3006451612903225" }, { "cost": "0", "date": "2026-05-21T00:00:00.000Z", "margin_amount": "246.3006451612903225", "margin_percent": 100, "revenue": "246.3006451612903225" }, { "cost": "0", "date": "2026-05-22T00:00:00.000Z", "margin_amount": "246.3006451612903225", "margin_percent": 100, "revenue": "246.3006451612903225" }, { "cost": "236.04", "date": "2026-05-23T00:00:00.000Z", "margin_amount": "10.2606451612903225", "margin_percent": 4.17, "revenue": "246.3006451612903225" }, { "cost": "0", "date": "2026-05-24T00:00:00.000Z", "margin_amount": "246.3006451612903225", "margin_percent": 100, "revenue": "246.3006451612903225" }, { "cost": "381.68", "date": "2026-05-25T00:00:00.000Z", "margin_amount": "-135.3793548387096775", "margin_percent": -54.97, "revenue": "246.3006451612903225" }, { "cost": "0", "date": "2026-05-26T00:00:00.000Z", "margin_amount": "246.3006451612903225", "margin_percent": 100, "revenue": "246.3006451612903225" }, { "cost": "190.84", "date": "2026-05-27T00:00:00.000Z", "margin_amount": "55.4606451612903225", "margin_percent": 22.52, "revenue": "246.3006451612903225" }, { "cost": "0", "date": "2026-05-28T00:00:00.000Z", "margin_amount": "246.3006451612903225", "margin_percent": 100, "revenue": "246.3006451612903225" }, { "cost": "0", "date": "2026-05-29T00:00:00.000Z", "margin_amount": "246.3006451612903225", "margin_percent": 100, "revenue": "246.3006451612903225" }, { "cost": "0", "date": "2026-05-30T00:00:00.000Z", "margin_amount": "246.3006451612903225", "margin_percent": 100, "revenue": "246.3006451612903225" }, { "cost": "0", "date": "2026-05-31T00:00:00.000Z", "margin_amount": "246.3006451612903225", "margin_percent": 100, "revenue": "246.3006451612903225" } ], "granularity": "daily" } } } }, "400": { "description": "Invalid query parameters. Check that start_date and end_date are valid ISO 8601 dates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/margin-data/trend", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/margin-data/trend", "method": "GET" } } } } }, "403": { "description": "API key lacks the revenue:read scope. Use a key that includes the revenue:read scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/margin-data/trend", "method": "GET" } } } } }, "422": { "description": "Date range exceeds 12 months. Narrow start_date and end_date to a span of 12 months or less.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNPROCESSABLE_ENTITY", "message": "Date range exceeds 12 months. Narrow start_date and end_date to a span of 12 months or less.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Date range exceeds 12 months. Narrow start_date and end_date to a span of 12 months or less.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/margin-data/trend", "method": "GET" } } } } }, "429": { "description": "Rate limit exceeded. Reduce request frequency and retry after the interval indicated in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/margin-data/trend", "method": "GET" } } } } } }, "description": "Get margin trend with adaptive granularity\n\nReturns time-series margin data (revenue - cost) with adaptive granularity:\n- <= 30 days: daily\n- 31-90 days: weekly\n- > 90 days: monthly\n\nPeriods with no revenue and no cost activity are omitted from data_points\nrather than returned as zero values. Zero-fill client-side if you need a\ncontinuous series.\n\nMargin requires revenue data from your connected Stripe account; connect\nit in your dashboard under Settings then Integrations. Note that a\nnot-yet-connected account and a genuine zero-revenue period both return\n\"0\", so verify the connection before interpreting zeros. If no\nrevenue has been synced for a period, its revenue field returns \"0\" and\nmargin_percent is null (division by zero is undefined).\n\nRevenue is recognized on an accrual basis: each revenue record's amount is\nattributed across its billing period. Costs are attributed to the time the\nusage event occurred.\n\n**Required Scope:** `revenue:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get margin trend", "tags": [ "Margin Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Start of date range (ISO 8601, inclusive).", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } }, { "description": "Optional end user to filter by. Pass the end_user_id (UUID) returned by GET /margin-data/by-end-user. This is Bear Lumen's internal end-user ID, not the external ID you send on usage events.", "in": "query", "name": "end_user_id", "required": false, "schema": { "type": "string" } } ], "x-required-scopes": [ "revenue:read" ] } }, "/insights/summary": { "get": { "operationId": "getInsightsSummary", "responses": { "200": { "description": "Insights summary retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightsSummaryResponseDTO" }, "example": { "correlations": { "cost_vs_request_volume": 0.52, "margin_vs_model_mix": -0.86 }, "distributions": { "cost_per_end_user": { "gini": 0.48, "mean": 1529.23, "median": 1543.26, "p25": 244.89, "p75": 2508.53, "p90": 3024.56, "p99": 3394.06, "skewness": 0.1, "std_dev": 1304.35, "top_decile_share": 37.4 }, "cost_per_request": { "mean": 349.1366, "median": 269.1531, "p25": 34.3266, "p75": 442.7363, "p90": 771.63, "p99": 1063.6305, "std_dev": 379.9823 }, "daily_cost": { "cv": 1.072, "max": 1204.63, "mean": 295.98, "median": 236.04, "min": 0.48, "std_dev": 317.44, "trend": { "direction": "increasing", "r2": 0.114, "slope": 11.9779 } }, "margin_per_end_user": { "below_zero_count": 1, "mean": 11.6, "median": 14, "p25": -10.1, "p75": 34.5, "p90": 46.8, "p99": 54.2, "skewness": -0.1, "std_dev": 36.5 }, "requests_per_end_user": { "mean": 7, "median": 3, "p25": 2, "p75": 7, "p90": 16, "p99": 23, "std_dev": 7.9 } }, "margin_outliers": [], "period": { "current": { "end": "2026-06-01T00:00:00.000Z", "start": "2026-01-01T00:00:00.000Z" }, "prior": { "end": "2026-01-01T00:00:00.000Z", "start": "2025-08-01T00:00:00.000Z" } }, "top_movers": { "by_custom_dimension": { "batch_size": [ { "change_percent": null, "cost": 7043.47, "end_user_count": 5, "prior": 0, "request_count": 34, "share_percent": 76.8, "value": "Unassigned", "z_score": 3.1 }, { "change_percent": -100, "cost": 0, "end_user_count": 0, "prior": 851.13, "request_count": 0, "share_percent": 0, "value": "104", "z_score": -0.8 }, { "change_percent": null, "cost": 612.44, "end_user_count": 0, "prior": 0, "request_count": 1, "share_percent": 6.7, "value": "128", "z_score": -0.1 }, { "change_percent": null, "cost": 484.72, "end_user_count": 0, "prior": 0, "request_count": 1, "share_percent": 5.3, "value": "256", "z_score": -0.1 }, { "change_percent": -100, "cost": 0, "end_user_count": 0, "prior": 412.55, "request_count": 0, "share_percent": 0, "value": "56", "z_score": -0.6 } ], "environment": [ { "change_percent": null, "cost": 7101.74, "end_user_count": 5, "prior": 0, "request_count": 35, "share_percent": 77.4, "value": "Unassigned", "z_score": 1.7 }, { "change_percent": 107, "cost": 1761.75, "end_user_count": 0, "prior": 851.13, "request_count": 4, "share_percent": 19.2, "value": "production", "z_score": -0.4 }, { "change_percent": -34.6, "cost": 269.71, "end_user_count": 0, "prior": 412.55, "request_count": 2, "share_percent": 2.9, "value": "staging", "z_score": -0.7 }, { "change_percent": null, "cost": 42.19, "end_user_count": 0, "prior": 0, "request_count": 1, "share_percent": 0.5, "value": "development", "z_score": -0.6 } ] }, "by_end_user": [ { "change_percent": null, "cost": 3435.12, "margin": 55, "margin_percentile": 100, "model_mix": { "claude-3-5-sonnet": 32.8, "gemini-2.0-flash": 5.6, "gpt-4o": 50.6, "gpt-4o-mini": 11.1 }, "percentile": 100, "prior": 0, "share_percent": 37.4, "value": "user_fixture_a", "z_score": 1.7 }, { "change_percent": null, "cost": 2192.15, "margin": 14, "margin_percentile": 66.7, "model_mix": { "claude-3-5-sonnet": 45, "gpt-4o": 55 }, "percentile": 66.7, "prior": 0, "share_percent": 23.9, "value": "user_fixture_b", "z_score": 0.7 }, { "change_percent": 106.9, "cost": 2613.99, "margin": null, "margin_percentile": null, "model_mix": {}, "percentile": 83.3, "prior": 1263.68, "share_percent": 28.5, "value": "Unassigned", "z_score": 0 }, { "change_percent": null, "cost": 894.37, "margin": -34.3, "margin_percentile": 33.3, "model_mix": { "gemini-2.0-flash": 42.7, "gpt-4o-mini": 57.3 }, "percentile": 50, "prior": 0, "share_percent": 9.7, "value": "user_fixture_c", "z_score": -0.4 }, { "change_percent": null, "cost": 28.39, "margin": null, "margin_percentile": null, "model_mix": { "claude-sonnet-4": 51.1, "gpt-4o": 42.5, "gpt-4o-mini": 6.4 }, "percentile": 33.3, "prior": 0, "share_percent": 0.3, "value": "user_7RkPq3Ne", "z_score": -1.1 } ], "by_model": [ { "avg_cost_per_request": 352.1362, "change_percent": 437.8, "cost": 4577.77, "prior": 851.13, "prior_share_percent": 67.4, "request_count": 13, "share_percent": 49.9, "value": "gpt-4o", "z_score": 1.9 }, { "avg_cost_per_request": 418.7971, "change_percent": 610.6, "cost": 2931.58, "prior": 412.55, "prior_share_percent": 32.6, "request_count": 7, "share_percent": 32, "value": "claude-3-5-sonnet", "z_score": 1 }, { "avg_cost_per_request": 105.1989, "change_percent": null, "cost": 946.79, "prior": 0, "prior_share_percent": 0, "request_count": 9, "share_percent": 10.3, "value": "gpt-4o-mini", "z_score": -0.1 }, { "avg_cost_per_request": 134.044, "change_percent": null, "cost": 670.22, "prior": 0, "prior_share_percent": 0, "request_count": 5, "share_percent": 7.3, "value": "gemini-2.0-flash", "z_score": -0.3 }, { "avg_cost_per_request": 12.515, "change_percent": null, "cost": 25.03, "prior": 0, "prior_share_percent": 0, "request_count": 2, "share_percent": 0.3, "value": "claude-sonnet-4", "z_score": -0.8 } ], "by_provider": [ { "change_percent": 551, "cost": 5540.56, "prior": 851.13, "prior_share_percent": 67.4, "share_percent": 60.4, "value": "openai", "z_score": 1.2 }, { "change_percent": 618.6, "cost": 2964.61, "prior": 412.55, "prior_share_percent": 32.6, "share_percent": 32.3, "value": "anthropic", "z_score": -0.1 }, { "change_percent": null, "cost": 670.22, "prior": 0, "prior_share_percent": 0, "share_percent": 7.3, "value": "google", "z_score": -1.2 } ] }, "totals": { "active_end_users": { "change_percent": null, "current": 5, "prior": 0 }, "cost": { "change_percent": 626.1, "current": 9175.39, "prior": 1263.68 }, "margin": { "change_points": 24.1, "current": 24.1, "prior": 0 }, "request_count": { "change_percent": 2000, "current": 42, "prior": 2 }, "revenue": { "change_percent": null, "current": 12091.52, "prior": 0 } }, "unmapped_spend": { "connect_billing_gap_cents": 3976, "connect_billing_gap_percent": 0.4, "instrumentation_gap_cents": 261399, "instrumentation_gap_percent": 28.5 } } } } }, "400": { "description": "Invalid request parameters. Check that start and end are valid ISO 8601 dates and that the requested range does not exceed 365 days.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/insights/summary", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/insights/summary", "method": "GET" } } } } }, "403": { "description": "Forbidden. The API key is missing the costs:read or revenue:read scope; create or update a key with both scopes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/insights/summary", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/insights/summary", "method": "GET" } } } } }, "503": { "description": "Service unavailable. The summary could not be computed due to a temporary database issue; retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable. Retry the request in a few moments.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Service is temporarily unavailable. Please try again in a few minutes.", "supportMessage": "If the service remains unavailable, please contact support with reference ID: OLIVE-DINOSAUR-1b2fE4", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/insights/summary", "method": "GET" } } } } } }, "description": "Get insights summary\n\nReturns period-over-period totals, population distributions,\ntop movers with z-scores, margin outliers, and cross-metric correlations.\nDesigned for AI agent consumption: pure statistical data, no narrative.\nUse this endpoint when you need distributions, z-scored top movers,\nmargin outliers, and correlations; use /cost-data/summary for a simple\ncost rollup with period comparison.\n\nAll monetary values are USD. Totals (cost, revenue), top-mover costs, and\ndistribution statistics are expressed in dollars; unmappedSpend fields are\ninteger cents.\n\n**Required Scopes:** `costs:read` AND `revenue:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get insights summary", "tags": [ "Insights API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Start of date range (ISO 8601, inclusive). Filters on event invocation time, evaluated in UTC. The requested range must not exceed 365 days; longer ranges return 400.", "in": "query", "name": "start", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive). Filters on event invocation time, evaluated in UTC. The requested range must not exceed 365 days; longer ranges return 400.", "in": "query", "name": "end", "required": true, "schema": { "type": "string" } }, { "description": "Optional sections to compute. Supported value: distributions. Unrecognized values are ignored. When omitted, the distributions field is null.", "in": "query", "name": "include", "required": false, "schema": { "type": "string" } }, { "description": "Maximum number of top movers per category. Default 5. Values outside 1-50 are clamped to the nearest bound, not rejected; non-integer values are accepted.", "in": "query", "name": "limit", "required": false, "schema": { "format": "double", "type": "number" } }, { "description": "Explicit prior period start (ISO 8601). Must be provided together with prior_end; if either is omitted, the prior period defaults to the window of equal length immediately preceding start.", "in": "query", "name": "prior_start", "required": false, "schema": { "type": "string" } }, { "description": "Explicit prior period end (ISO 8601, exclusive). Must be provided together with prior_start; if either is omitted, the prior period defaults to the window of equal length immediately preceding start.", "in": "query", "name": "prior_end", "required": false, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read", "revenue:read" ] } }, "/end-user-costs/{externalId}/summary": { "get": { "operationId": "getEndUserCostsSummary", "responses": { "200": { "description": "End user cost summary retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndUserCostsSummaryResponseDTO" }, "example": { "change_amount": "381.68", "change_percent": 25, "current_period_cost": "1908.4", "end_user_external_id": "user_fixture_a", "end_user_id": "eb77aa11-0001-7777-9a1b-2c3d4e5f6a01", "end_user_name": "Aurora Systems", "event_count": 6, "period_end": "2026-06-01T00:00:00.000Z", "period_start": "2026-05-15T00:00:00.000Z", "previous_period_cost": "1526.72" } } } }, "400": { "description": "Invalid request data. Check that required query parameters are present and that start_date and end_date are valid ISO 8601 dates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/summary", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/summary", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update a key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/summary", "method": "GET" } } } } }, "404": { "description": "End user not found. The identifier must match the user_id value sent on at least one ingested usage event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Resource not found or not accessible with this API key. Check the identifier and try again.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Resource not found or not accessible with this API key. Check the identifier and try again.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/summary", "method": "GET" } } } } }, "429": { "description": "Rate limit exceeded. Retry after the time indicated by the Retry-After header (rate-limit state is also reported in the standard RateLimit-* headers, e.g. RateLimit-Reset).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/summary", "method": "GET" } } } } } }, "description": "Get end user cost summary\n\nReturns cost summary for the specified end-user with comparison to the previous period.\nThe previous period is automatically calculated as the same-length period immediately\nbefore the start_date.\n\n**Required Scope:** `costs:read`\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get end user cost summary", "tags": [ "End User Costs API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "End-user identifier you assigned when sending usage events (the user_id field on POST /usage-events). An end user exists only after at least one event referencing this identifier has been ingested; unknown identifiers return 404.", "in": "path", "name": "externalId", "required": true, "schema": { "type": "string" } }, { "description": "Start of date range (ISO 8601, inclusive).", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/end-user-costs/{externalId}/by-model": { "get": { "operationId": "getEndUserCostsByModel", "responses": { "200": { "description": "End user model breakdown retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndUserCostsModelBreakdownResponseDTO" }, "example": { "end_user_id": "eb77aa11-0001-7777-9a1b-2c3d4e5f6a01", "models": [ { "cache_creation_cost": "1.86", "cache_creation_input_tokens": 88400, "cache_read_cost": "1.21", "cache_read_input_tokens": 403200, "event_count": 2, "input_cost": "507.03", "input_tokens": 729100, "model_slug": "gpt-4o", "output_cost": "253.26", "output_tokens": 182700, "percent_of_total": 40, "provider_slug": "unknown", "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "763.36" }, { "cache_creation_cost": null, "cache_creation_input_tokens": null, "cache_read_cost": null, "cache_read_input_tokens": null, "event_count": 2, "input_cost": "381.68", "input_tokens": 555300, "model_slug": "claude-3-5-sonnet", "output_cost": "190.84", "output_tokens": 138800, "percent_of_total": 30, "provider_slug": "unknown", "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "572.52" }, { "cache_creation_cost": null, "cache_creation_input_tokens": null, "cache_read_cost": null, "cache_read_input_tokens": null, "event_count": 1, "input_cost": "254.45", "input_tokens": 1183100, "model_slug": "gpt-4o-mini", "output_cost": "127.23", "output_tokens": 295800, "percent_of_total": 20, "provider_slug": "unknown", "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "381.68" }, { "cache_creation_cost": null, "cache_creation_input_tokens": null, "cache_read_cost": null, "cache_read_input_tokens": null, "event_count": 1, "input_cost": "127.23", "input_tokens": 883100, "model_slug": "gemini-2.0-flash", "output_cost": "63.61", "output_tokens": 220800, "percent_of_total": 10, "provider_slug": "unknown", "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "190.84" } ], "total_cost": "1908.4" } } } }, "400": { "description": "Invalid request data. Check that required query parameters are present and that start_date and end_date are valid ISO 8601 dates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/by-model", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/by-model", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update a key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/by-model", "method": "GET" } } } } }, "404": { "description": "End user not found. The identifier must match the user_id value sent on at least one ingested usage event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Resource not found or not accessible with this API key. Check the identifier and try again.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Resource not found or not accessible with this API key. Check the identifier and try again.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/by-model", "method": "GET" } } } } }, "429": { "description": "Rate limit exceeded. Retry after the time indicated by the Retry-After header (rate-limit state is also reported in the standard RateLimit-* headers, e.g. RateLimit-Reset).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/by-model", "method": "GET" } } } } } }, "description": "Get cost breakdown by model for a specific end-user\n\nReturns cost aggregation grouped by AI model for the specified end-user.\n\n**Required Scope:** `costs:read`\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get cost breakdown by model for a specific end-user", "tags": [ "End User Costs API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "End-user identifier you assigned when sending usage events (the user_id field on POST /usage-events). An end user exists only after at least one event referencing this identifier has been ingested; unknown identifiers return 404.", "in": "path", "name": "externalId", "required": true, "schema": { "type": "string" } }, { "description": "Start of date range (ISO 8601, inclusive).", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/end-user-costs/{externalId}/by-provider": { "get": { "operationId": "getEndUserCostsByProvider", "responses": { "200": { "description": "End user provider breakdown retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndUserCostsProviderBreakdownResponseDTO" }, "example": { "end_user_id": "eb77aa11-0001-7777-9a1b-2c3d4e5f6a01", "providers": [ { "event_count": 3, "percent_of_total": 60, "provider_name": "openai", "provider_slug": "openai", "total_cost": "1145.04" }, { "event_count": 2, "percent_of_total": 30, "provider_name": "anthropic", "provider_slug": "anthropic", "total_cost": "572.52" }, { "event_count": 1, "percent_of_total": 10, "provider_name": "google", "provider_slug": "google", "total_cost": "190.84" } ], "total_cost": "1908.4" } } } }, "400": { "description": "Invalid request data. Check that required query parameters are present and that start_date and end_date are valid ISO 8601 dates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/by-provider", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/by-provider", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update a key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/by-provider", "method": "GET" } } } } }, "404": { "description": "End user not found. The identifier must match the user_id value sent on at least one ingested usage event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Resource not found or not accessible with this API key. Check the identifier and try again.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Resource not found or not accessible with this API key. Check the identifier and try again.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/by-provider", "method": "GET" } } } } }, "429": { "description": "Rate limit exceeded. Retry after the time indicated by the Retry-After header (rate-limit state is also reported in the standard RateLimit-* headers, e.g. RateLimit-Reset).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/by-provider", "method": "GET" } } } } } }, "description": "Get cost breakdown by provider for a specific end-user\n\nReturns cost aggregation grouped by AI provider for the specified end-user.\n\n**Required Scope:** `costs:read`\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get cost breakdown by provider for a specific end-user", "tags": [ "End User Costs API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "End-user identifier you assigned when sending usage events (the user_id field on POST /usage-events). An end user exists only after at least one event referencing this identifier has been ingested; unknown identifiers return 404.", "in": "path", "name": "externalId", "required": true, "schema": { "type": "string" } }, { "description": "Start of date range (ISO 8601, inclusive).", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/end-user-costs/{externalId}/trend": { "get": { "operationId": "getEndUserCostsTrend", "responses": { "200": { "description": "End user cost trend retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndUserCostsTrendResponseDTO" }, "example": { "end_user_id": "eb77aa11-0001-7777-9a1b-2c3d4e5f6a01", "granularity": "daily", "series": [ { "data_points": [ { "cost": "522.3", "date": "2026-05-16T00:00:00.000Z", "event_count": 1 }, { "cost": "336.48", "date": "2026-05-18T00:00:00.000Z", "event_count": 1 }, { "cost": "241.06", "date": "2026-05-20T00:00:00.000Z", "event_count": 1 }, { "cost": "236.04", "date": "2026-05-23T00:00:00.000Z", "event_count": 1 }, { "cost": "381.68", "date": "2026-05-25T00:00:00.000Z", "event_count": 1 }, { "cost": "190.84", "date": "2026-05-27T00:00:00.000Z", "event_count": 1 } ], "key": "user_fixture_a", "label": "user_fixture_a" } ] } } } }, "400": { "description": "Invalid request data. Check that required query parameters are present and that start_date and end_date are valid ISO 8601 dates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/trend", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/trend", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update a key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/trend", "method": "GET" } } } } }, "404": { "description": "End user not found. The identifier must match the user_id value sent on at least one ingested usage event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Resource not found or not accessible with this API key. Check the identifier and try again.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Resource not found or not accessible with this API key. Check the identifier and try again.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/trend", "method": "GET" } } } } }, "429": { "description": "Rate limit exceeded. Retry after the time indicated by the Retry-After header (rate-limit state is also reported in the standard RateLimit-* headers, e.g. RateLimit-Reset).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/trend", "method": "GET" } } } } } }, "description": "Get cost trend for a specific end-user\n\nReturns time-series cost data with adaptive granularity for the specified end-user.\nGranularity is selected from the date range: 30 days or less returns daily points,\n31-90 days weekly, longer ranges monthly. The response granularity field reports\nwhich was used.\n\nPeriods with no events are omitted from dataPoints (not returned as zero-cost\npoints); fill gaps client-side if your chart requires a continuous series.\n\n**Required Scope:** `costs:read`\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get cost trend for a specific end-user", "tags": [ "End User Costs API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "End-user identifier you assigned when sending usage events (the user_id field on POST /usage-events). An end user exists only after at least one event referencing this identifier has been ingested; unknown identifiers return 404.", "in": "path", "name": "externalId", "required": true, "schema": { "type": "string" } }, { "description": "Start of date range (ISO 8601, inclusive).", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/end-user-costs/{externalId}/by-dimension": { "get": { "operationId": "getEndUserCostsByDimension", "responses": { "200": { "description": "End user dimension breakdown retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndUserCostsDimensionBreakdownResponseDTO" }, "example": { "end_user_id": "eb77aa11-0001-7777-9a1b-2c3d4e5f6a01", "items": [ { "attribution_value": "chat-completion", "cache_creation_cost": "1.86", "cache_creation_input_tokens": 88400, "cache_read_cost": "1.21", "cache_read_input_tokens": 403200, "event_count": 2, "input_cost": "570.64", "input_tokens": 821000, "output_cost": "285.07", "output_tokens": 205700, "percent_of_total": 45, "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "858.78" }, { "attribution_value": "summarization", "cache_creation_cost": null, "cache_creation_input_tokens": null, "cache_read_cost": null, "cache_read_input_tokens": null, "event_count": 3, "input_cost": "445.3", "input_tokens": 1346500, "output_cost": "222.64", "output_tokens": 336600, "percent_of_total": 35, "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "667.94" }, { "attribution_value": "Unassigned", "cache_creation_cost": null, "cache_creation_input_tokens": null, "cache_read_cost": null, "cache_read_input_tokens": null, "event_count": 1, "input_cost": "254.45", "input_tokens": 1183100, "output_cost": "127.23", "output_tokens": 295800, "percent_of_total": 20, "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "381.68" } ], "total_cost": "1908.4" } } } }, "400": { "description": "Invalid request data. Check that required query parameters are present and that start_date and end_date are valid ISO 8601 dates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/by-dimension", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/by-dimension", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update a key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/by-dimension", "method": "GET" } } } } }, "404": { "description": "End user not found. The identifier must match the user_id value sent on at least one ingested usage event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Resource not found or not accessible with this API key. Check the identifier and try again.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Resource not found or not accessible with this API key. Check the identifier and try again.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/by-dimension", "method": "GET" } } } } }, "429": { "description": "Rate limit exceeded. Retry after the time indicated by the Retry-After header (rate-limit state is also reported in the standard RateLimit-* headers, e.g. RateLimit-Reset).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/end-user-costs/{externalId}/by-dimension", "method": "GET" } } } } } }, "description": "Get cost breakdown by dimension for a specific end-user\n\nReturns cost aggregation grouped by a metadata dimension key for the specified end-user.\nEvents that do not carry the requested key are grouped under the literal value\n\"Unassigned\". A key that no events carry does not return an error; it returns the\nfull cost in a single \"Unassigned\" row, so verify the key name if you see 100%\nUnassigned.\n\n**Required Scope:** `costs:read`\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get cost breakdown by dimension for a specific end-user", "tags": [ "End User Costs API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "End-user identifier you assigned when sending usage events (the user_id field on POST /usage-events). An end user exists only after at least one event referencing this identifier has been ingested; unknown identifiers return 404.", "in": "path", "name": "externalId", "required": true, "schema": { "type": "string" } }, { "description": "Metadata dimension key to group by (e.g., 'feature', 'team', 'agent_id'). Only 'feature' reads a typed event field; every other key is looked up in event metadata. For per-model or per-provider breakdowns use the dedicated /by-model and /by-provider endpoints instead of a metadata key.", "in": "query", "name": "dimension", "required": true, "schema": { "type": "string" } }, { "description": "Start of date range (ISO 8601, inclusive).", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/dimension-data/definitions": { "get": { "operationId": "getDimensionDefinitions", "responses": { "200": { "description": "Dimension definitions retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DimensionDataDefinitionsResponseDTO" }, "example": { "dimensions": [ { "created_at": "2026-01-05T09:12:00.000Z", "description": "Deployment environment that generated the AI usage", "id": "dd88c1a2-0001-8888-9a1b-2c3d4e5f6a01", "is_required": false, "key": "environment", "name": "Environment", "organization_id": "b7e6a3f2-4c1d-4e8a-9b5f-2d7c8e1a6f43", "value_type": "string" }, { "created_at": "2026-01-08T14:30:00.000Z", "description": "Number of documents processed per pipeline batch", "id": "dd88c1a2-0002-8888-9a1b-2c3d4e5f6a02", "is_required": false, "key": "batch_size", "name": "Batch Size", "organization_id": "b7e6a3f2-4c1d-4e8a-9b5f-2d7c8e1a6f43", "value_type": "number" } ], "total": 2 } } } }, "401": { "description": "Authentication required. Provide a valid API key in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/definitions", "method": "GET" } } } } }, "403": { "description": "Insufficient permissions. Use an API key with the dimensions:read scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/definitions", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/definitions", "method": "GET" } } } } } }, "description": "List custom dimension definitions\n\nReturns all dimension definitions for the organization.\nDimensions define the metadata keys that can be used to filter and group costs.\n\nDimension values are supplied through the `metadata` object on usage events sent to\n`POST /usage-events`. Dimensions marked `isRequired` are enforced at ingestion: events\nmissing the key are rejected. Numeric dimensions (`value_type` \"number\") require a finite\nJSON number value and can be aggregated via `/dimension-data/numeric-summary` and\n`/dimension-data/numeric-trend`.\n\n**Required Scope:** `dimensions:read`\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get dimension definitions", "tags": [ "Dimension Data API" ], "security": [ { "apiKey": [] } ], "parameters": [], "x-required-scopes": [ "dimensions:read" ] } }, "/dimension-data/cost-breakdown": { "get": { "operationId": "getDimensionCostBreakdown", "responses": { "200": { "description": "Cost breakdown retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DimensionDataCostBreakdownResponseDTO" }, "example": { "items": [ { "dimension_value": "production", "event_count": 4, "input_tokens": 1712800, "output_tokens": 428100, "percent_of_total": 80.71462278198004, "total_cost": "1761.75" }, { "dimension_value": "staging", "event_count": 2, "input_tokens": 457300, "output_tokens": 114300, "percent_of_total": 12.35677077367835, "total_cost": "269.71" }, { "dimension_value": "Unassigned", "event_count": 9, "input_tokens": 25880200, "output_tokens": 5415300, "percent_of_total": 4.995670480004032, "total_cost": "109.04" }, { "dimension_value": "development", "event_count": 1, "input_tokens": 132700, "output_tokens": 33200, "percent_of_total": 1.9329359643375834, "total_cost": "42.19" } ], "total_cost": "2182.69" } } } }, "400": { "description": "Invalid request. Check that start_date and end_date are valid ISO 8601 dates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/cost-breakdown", "method": "GET" } } } } }, "401": { "description": "Authentication required. Provide a valid API key in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/cost-breakdown", "method": "GET" } } } } }, "403": { "description": "Insufficient permissions. Use an API key with the costs:read scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/cost-breakdown", "method": "GET" } } } } }, "404": { "description": "Dimension not found. Pass a dimension_key exactly as returned by GET /dimension-data/definitions (snake_case, case-sensitive).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Resource not found or not accessible with this API key. Check the identifier and try again.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Resource not found or not accessible with this API key. Check the identifier and try again.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/cost-breakdown", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/cost-breakdown", "method": "GET" } } } } } }, "description": "Get cost breakdown by dimension value\n\nReturns cost aggregated by a specific custom dimension (e.g., \"team\", \"region\").\nGroups costs by the dimension values (e.g., \"team-ml\", \"team-api\").\n\nEvents that do not carry the dimension key in their metadata are grouped under the\nreserved dimensionValue \"Unassigned\".\n\n**Required Scope:** `costs:read`\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get cost breakdown by dimension", "tags": [ "Dimension Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Dimension key exactly as returned by GET /dimension-data/definitions (snake_case, case-sensitive).", "in": "query", "name": "dimension_key", "required": true, "schema": { "type": "string" } }, { "description": "Start of date range (ISO 8601, inclusive).", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/dimension-data/cost-trend": { "get": { "operationId": "getDimensionCostTrend", "responses": { "200": { "description": "Cost trend retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DimensionDataCostTrendResponseDTO" }, "example": { "granularity": "daily", "series": [ { "data_points": [ { "cost": "612.44", "date": "2026-01-04T00:00:00.000Z", "event_count": 1 }, { "cost": "484.72", "date": "2026-01-09T00:00:00.000Z", "event_count": 1 }, { "cost": "389.61", "date": "2026-01-15T00:00:00.000Z", "event_count": 1 }, { "cost": "274.98", "date": "2026-01-21T00:00:00.000Z", "event_count": 1 } ], "key": "production", "label": "production" }, { "data_points": [ { "cost": "173.58", "date": "2026-01-13T00:00:00.000Z", "event_count": 1 }, { "cost": "96.13", "date": "2026-01-17T00:00:00.000Z", "event_count": 1 } ], "key": "staging", "label": "staging" }, { "data_points": [ { "cost": "12.07", "date": "2026-01-05T00:00:00.000Z", "event_count": 1 }, { "cost": "16.32", "date": "2026-01-08T00:00:00.000Z", "event_count": 2 }, { "cost": "9.37", "date": "2026-01-12T00:00:00.000Z", "event_count": 1 }, { "cost": "0.59", "date": "2026-01-15T00:00:00.000Z", "event_count": 1 }, { "cost": "10.53", "date": "2026-01-19T00:00:00.000Z", "event_count": 1 }, { "cost": "1.41", "date": "2026-01-22T00:00:00.000Z", "event_count": 1 }, { "cost": "58.27", "date": "2026-01-26T00:00:00.000Z", "event_count": 1 }, { "cost": "0.48", "date": "2026-01-27T00:00:00.000Z", "event_count": 1 } ], "key": "Unassigned", "label": "Unassigned" }, { "data_points": [ { "cost": "42.19", "date": "2026-01-22T00:00:00.000Z", "event_count": 1 } ], "key": "development", "label": "development" } ] } } } }, "400": { "description": "Invalid request. Check that start_date and end_date are valid ISO 8601 dates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/cost-trend", "method": "GET" } } } } }, "401": { "description": "Authentication required. Provide a valid API key in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/cost-trend", "method": "GET" } } } } }, "403": { "description": "Insufficient permissions. Use an API key with the costs:read scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/cost-trend", "method": "GET" } } } } }, "404": { "description": "Dimension not found. Pass a dimension_key exactly as returned by GET /dimension-data/definitions (snake_case, case-sensitive).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Resource not found or not accessible with this API key. Check the identifier and try again.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Resource not found or not accessible with this API key. Check the identifier and try again.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/cost-trend", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/cost-trend", "method": "GET" } } } } } }, "description": "Get cost trend filtered/grouped by dimension\n\nReturns time-series cost data with adaptive granularity based on date range.\nCan filter by specific dimension value or group by dimension.\n\nAdaptive granularity: date ranges of 30 days or less return daily buckets, 31-90 days\nreturn weekly, and longer ranges return monthly. Granularity cannot be overridden on\nthis endpoint; only `/dimension-data/numeric-trend` accepts an `interval` parameter.\nThe response `granularity` field reports which bucket size was used.\n\n**Modes:**\n- No dimension params: Returns single \"Total\" series (all costs)\n- `dimension_key` only: Returns top 5 dimension values as series + \"Other\"\n- `dimension_key` + `dimension_value`: Returns single series filtered by that value\n\nWhen grouping by `dimension_key`, events that do not carry the dimension key in their\nmetadata are grouped under the reserved value \"Unassigned\".\n\n**Required Scope:** `costs:read`\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get cost trend by dimension", "tags": [ "Dimension Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Start of date range (ISO 8601, inclusive).", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } }, { "description": "Optional dimension key to filter/group by, exactly as returned by GET /dimension-data/definitions (snake_case, case-sensitive).", "in": "query", "name": "dimension_key", "required": false, "schema": { "type": "string" } }, { "description": "Optional specific dimension value to filter to.", "in": "query", "name": "dimension_value", "required": false, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/dimension-data/numeric-summary": { "get": { "operationId": "getNumericDimensionSummary", "responses": { "200": { "description": "Numeric dimension summary retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DimensionDataNumericSummaryResponseDTO" }, "example": { "aggregation": "sum", "dimension_key": "batch_size", "event_count": 8, "value": "928" } } } }, "400": { "description": "Invalid request. Check date formats, use an aggregation of sum, avg, min, or max, and target a dimension with value_type \"number\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/numeric-summary", "method": "GET" } } } } }, "401": { "description": "Authentication required. Provide a valid API key in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/numeric-summary", "method": "GET" } } } } }, "403": { "description": "Insufficient permissions. Use an API key with the costs:read scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/numeric-summary", "method": "GET" } } } } }, "404": { "description": "Dimension not found. Pass a dimension_key exactly as returned by GET /dimension-data/definitions (snake_case, case-sensitive).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Resource not found or not accessible with this API key. Check the identifier and try again.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Resource not found or not accessible with this API key. Check the identifier and try again.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/numeric-summary", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/numeric-summary", "method": "GET" } } } } } }, "description": "Get numeric dimension summary aggregation\n\nReturns a single aggregated numeric value (SUM/AVG/MIN/MAX) for a numeric custom dimension.\nOnly works with dimensions of value_type 'number'.\n\n**Required Scope:** `costs:read`\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get numeric dimension summary", "tags": [ "Dimension Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Numeric dimension key to aggregate, exactly as returned by GET /dimension-data/definitions (snake_case, case-sensitive).", "in": "query", "name": "dimension_key", "required": true, "schema": { "type": "string" } }, { "description": "Aggregation function (sum, avg, min, max).", "in": "query", "name": "aggregation", "required": true, "schema": { "type": "string", "enum": [ "sum", "avg", "min", "max" ] } }, { "description": "Start of date range (ISO 8601, inclusive).", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/dimension-data/numeric-trend": { "get": { "operationId": "getNumericDimensionTrend", "responses": { "200": { "description": "Numeric dimension trend retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DimensionDataNumericTrendResponseDTO" }, "example": { "aggregation": "sum", "data_points": [ { "date": "2025-12-29T00:00:00.000Z", "event_count": 1, "value": "128" }, { "date": "2026-01-05T00:00:00.000Z", "event_count": 1, "value": "256" }, { "date": "2026-01-12T00:00:00.000Z", "event_count": 3, "value": "272" }, { "date": "2026-01-19T00:00:00.000Z", "event_count": 2, "value": "224" }, { "date": "2026-01-26T00:00:00.000Z", "event_count": 1, "value": "48" } ], "dimension_key": "batch_size", "granularity": "weekly" } } } }, "400": { "description": "Invalid request. Check date formats, use an aggregation of sum, avg, min, or max, an interval of daily, weekly, or monthly, and target a dimension with value_type \"number\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/numeric-trend", "method": "GET" } } } } }, "401": { "description": "Authentication required. Provide a valid API key in the Authorization header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/numeric-trend", "method": "GET" } } } } }, "403": { "description": "Insufficient permissions. Use an API key with the costs:read scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/numeric-trend", "method": "GET" } } } } }, "404": { "description": "Dimension not found. Pass a dimension_key exactly as returned by GET /dimension-data/definitions (snake_case, case-sensitive).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Resource not found or not accessible with this API key. Check the identifier and try again.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Resource not found or not accessible with this API key. Check the identifier and try again.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/numeric-trend", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/dimension-data/numeric-trend", "method": "GET" } } } } } }, "description": "Get numeric dimension trend (time-series aggregation)\n\nReturns time-bucketed aggregated numeric values (SUM/AVG/MIN/MAX) for a numeric custom dimension.\nGranularity is adaptive based on date range, or can be specified explicitly via interval.\nOnly works with dimensions of value_type 'number'.\n\nAdaptive granularity: date ranges of 30 days or less return daily buckets, 31-90 days\nreturn weekly, and longer ranges return monthly. Pass `interval` to override. The\nresponse `granularity` field reports which bucket size was used.\n\n**Required Scope:** `costs:read`\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get numeric dimension trend", "tags": [ "Dimension Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Numeric dimension key to aggregate, exactly as returned by GET /dimension-data/definitions (snake_case, case-sensitive).", "in": "query", "name": "dimension_key", "required": true, "schema": { "type": "string" } }, { "description": "Aggregation function (sum, avg, min, max).", "in": "query", "name": "aggregation", "required": true, "schema": { "type": "string", "enum": [ "sum", "avg", "min", "max" ] } }, { "description": "Start of date range (ISO 8601, inclusive).", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } }, { "description": "Optional granularity override (daily, weekly, monthly).", "in": "query", "name": "interval", "required": false, "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] } } ], "x-required-scopes": [ "costs:read" ] } }, "/cost-data/summary": { "get": { "operationId": "getCostDataSummary", "responses": { "200": { "description": "Cost summary retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CostDataSummaryResponseDTO" }, "example": { "change_amount": "843.674", "change_percent": 25, "current_period_cost": "4218.37", "event_count": 3, "period_end": "2026-01-21T16:45:00.000Z", "period_start": "2026-01-01T00:00:00.000Z", "previous_period_cost": "3374.696", "status_counts": { "completed": 64, "failed": 0, "pending": 0, "pending_rate_card": 0 } } } } }, "400": { "description": "Invalid time_window. Use one of: current-period, last-period, last-7-days, last-30-days, last-90-days, ytd, last-year.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/summary", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/summary", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update a key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/summary", "method": "GET" } } } } }, "429": { "description": "Rate limit exceeded. The general API tier allows 100 requests per 15 minutes; wait for the window to reset before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/summary", "method": "GET" } } } } } }, "description": "Get cost summary\n\nReturns the organization-wide total cost for the selected time window along\nwith a comparison to the previous period, showing change amount and\npercentage to track cost trends. For a single end user's summary, use\nGET /end-user-costs/{externalId}/summary instead.\n\n**Required Scope:** `costs:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get cost summary", "tags": [ "Cost Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Time window preset (default 'current-period' = the current calendar month to date; 'last-period' = the previous calendar month).", "in": "query", "name": "time_window", "required": false, "schema": { "$ref": "#/components/schemas/TimeWindow" } } ], "x-required-scopes": [ "costs:read" ] } }, "/cost-data/by-end-user": { "get": { "operationId": "getCostDataByEndUser", "responses": { "200": { "description": "End user breakdown retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CostDataEndUserBreakdownResponseDTO" }, "example": { "end_users": [ { "cache_creation_cost": "0.53", "cache_creation_input_tokens": 141000, "cache_read_cost": "0.27", "cache_read_input_tokens": 890000, "end_user_id": "unassigned", "end_user_name": "Unassigned", "event_count": 10, "input_cost": "1425.26", "input_tokens": 6193200, "output_cost": "716.87", "output_tokens": 1503600, "percent_of_total": 98.17839454984446, "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "2142.93" }, { "cache_creation_cost": "0.83", "cache_creation_input_tokens": 220000, "cache_read_cost": "0.42", "cache_read_input_tokens": 1410000, "end_user_id": "ea1b2c3d-9999-4e4f-9a5b-6c7d8e9f0a01", "end_user_name": "Northwind Robotics", "event_count": 3, "input_cost": "14.59", "input_tokens": 11304700, "output_cost": "12.55", "output_tokens": 2394100, "percent_of_total": 1.3006885998469777, "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "28.39" }, { "cache_creation_cost": null, "cache_creation_input_tokens": null, "cache_read_cost": null, "cache_read_input_tokens": null, "end_user_id": "ea1b2c3d-9999-4e4f-9a5b-6c7d8e9f0a02", "end_user_name": "Cascade Analytics", "event_count": 3, "input_cost": "7.25", "input_tokens": 10685100, "output_cost": "4.12", "output_tokens": 2093200, "percent_of_total": 0.5209168503085642, "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "11.37" } ], "total_cost": "2182.69" } } } }, "400": { "description": "Invalid request data. Ensure start_date and end_date are valid ISO 8601 dates and start_date is before end_date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/by-end-user", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/by-end-user", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update a key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/by-end-user", "method": "GET" } } } } }, "429": { "description": "Rate limit exceeded. The general API tier allows 100 requests per 15 minutes; wait for the window to reset before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/by-end-user", "method": "GET" } } } } } }, "description": "Get cost breakdown by end user\n\nReturns organization-wide cost aggregation grouped by end user (your customers).\nEvents without an end user are bucketed as \"Unassigned\". All end users are\nreturned (no truncation), so entries always sum to total_cost.\n\nEach end_user_id is Bear Lumen's internal end-user UUID (or the literal\n'unassigned'), not the external_id you supplied on usage events. Use this\nendpoint to rank spend across all of your end users. For a per-end-user\ndrill-down (per-model, per-provider, trend, per-dimension), use the\nEnd User Costs API endpoints under /end-user-costs/{externalId}, which are\naddressed by the external_id you supplied on usage events.\n\n**Required Scope:** `costs:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get organization-wide cost breakdown by end user", "tags": [ "Cost Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Start of date range (ISO 8601, inclusive). Must be before end_date.", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/cost-data/by-provider": { "get": { "operationId": "getCostDataByProvider", "responses": { "200": { "description": "Provider breakdown retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CostDataProviderBreakdownResponseDTO" }, "example": { "providers": [ { "event_count": 8, "percent_of_total": 56.924712167096565, "provider_id": "unknown", "provider_name": "openai", "provider_slug": "openai", "total_cost": "1242.49" }, { "event_count": 5, "percent_of_total": 38.62206726562178, "provider_id": "unknown", "provider_name": "anthropic", "provider_slug": "anthropic", "total_cost": "843" }, { "event_count": 3, "percent_of_total": 4.453220567281657, "provider_id": "unknown", "provider_name": "google", "provider_slug": "google", "total_cost": "97.2" } ], "total_cost": "2182.69" } } } }, "400": { "description": "Invalid request data. Ensure start_date and end_date are valid ISO 8601 dates and start_date is before end_date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/by-provider", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/by-provider", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update a key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/by-provider", "method": "GET" } } } } }, "429": { "description": "Rate limit exceeded. The general API tier allows 100 requests per 15 minutes; wait for the window to reset before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/by-provider", "method": "GET" } } } } } }, "description": "Get cost breakdown by provider\n\nReturns organization-wide cost aggregation grouped by AI provider.\nprovider_name reflects the provider string reported on your usage events\nwhen present (typically a lowercase slug such as 'openai'), otherwise the\ncatalog display name.\n\n**Required Scope:** `costs:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get organization-wide cost breakdown by provider", "tags": [ "Cost Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Start of date range (ISO 8601, inclusive). Must be before end_date.", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/cost-data/by-model": { "get": { "operationId": "getCostDataByModel", "responses": { "200": { "description": "Model breakdown retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CostDataModelBreakdownResponseDTO" }, "example": { "models": [ { "cache_creation_cost": null, "cache_creation_input_tokens": null, "cache_read_cost": null, "cache_read_input_tokens": null, "event_count": 5, "input_cost": "797.87", "input_tokens": 6780600, "model_slug": "gpt-4o", "output_cost": "399.2", "output_tokens": 1016600, "percent_of_total": 54.84379366744705, "provider_slug": "unknown", "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "1197.07" }, { "cache_creation_cost": null, "cache_creation_input_tokens": null, "cache_read_cost": null, "cache_read_input_tokens": null, "event_count": 3, "input_cost": "545.32", "input_tokens": 794200, "model_slug": "claude-3-5-sonnet", "output_cost": "272.65", "output_tokens": 198500, "percent_of_total": 37.47531715452034, "provider_slug": "unknown", "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "817.97" }, { "cache_creation_cost": null, "cache_creation_input_tokens": null, "cache_read_cost": null, "cache_read_input_tokens": null, "event_count": 3, "input_cost": "64.7", "input_tokens": 6238400, "model_slug": "gemini-2.0-flash", "output_cost": "32.5", "output_tokens": 1239100, "percent_of_total": 4.453220567281657, "provider_slug": "unknown", "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "97.2" }, { "cache_creation_cost": null, "cache_creation_input_tokens": null, "cache_read_cost": null, "cache_read_input_tokens": null, "event_count": 3, "input_cost": "29.8", "input_tokens": 11236700, "model_slug": "gpt-4o-mini", "output_cost": "15.62", "output_tokens": 2633200, "percent_of_total": 2.080918499649515, "provider_slug": "unknown", "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "45.42" }, { "cache_creation_cost": "1.36", "cache_creation_input_tokens": 361000, "cache_read_cost": "0.69", "cache_read_input_tokens": 2300000, "event_count": 2, "input_cost": "9.41", "input_tokens": 3133100, "model_slug": "claude-sonnet-4", "output_cost": "13.57", "output_tokens": 903500, "percent_of_total": 1.146750111101439, "provider_slug": "unknown", "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "25.03" } ], "total_cost": "2182.69" } } } }, "400": { "description": "Invalid request data. Ensure start_date and end_date are valid ISO 8601 dates and start_date is before end_date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/by-model", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/by-model", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update a key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/by-model", "method": "GET" } } } } }, "429": { "description": "Rate limit exceeded. The general API tier allows 100 requests per 15 minutes; wait for the window to reset before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/by-model", "method": "GET" } } } } } }, "description": "Get cost breakdown by model\n\nReturns organization-wide cost aggregation grouped by AI model\n(gpt-4o, claude-3-5-sonnet, etc.). All models are returned (no\ntruncation), so entries always sum to total_cost.\n\n**Required Scope:** `costs:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get organization-wide cost breakdown by model", "tags": [ "Cost Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Start of date range (ISO 8601, inclusive). Must be before end_date.", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/cost-data/trend": { "get": { "operationId": "getCostDataTrend", "responses": { "200": { "description": "Cost trend retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CostDataTrendResponseDTO" }, "example": { "granularity": "daily", "series": [ { "data_points": [ { "cost": "612.44", "date": "2026-01-04T00:00:00.000Z", "event_count": 1 }, { "cost": "12.07", "date": "2026-01-05T00:00:00.000Z", "event_count": 1 }, { "cost": "16.32", "date": "2026-01-08T00:00:00.000Z", "event_count": 2 }, { "cost": "484.72", "date": "2026-01-09T00:00:00.000Z", "event_count": 1 }, { "cost": "9.37", "date": "2026-01-12T00:00:00.000Z", "event_count": 1 }, { "cost": "173.58", "date": "2026-01-13T00:00:00.000Z", "event_count": 1 }, { "cost": "390.2", "date": "2026-01-15T00:00:00.000Z", "event_count": 2 }, { "cost": "96.13", "date": "2026-01-17T00:00:00.000Z", "event_count": 1 }, { "cost": "10.53", "date": "2026-01-19T00:00:00.000Z", "event_count": 1 }, { "cost": "274.98", "date": "2026-01-21T00:00:00.000Z", "event_count": 1 }, { "cost": "43.6", "date": "2026-01-22T00:00:00.000Z", "event_count": 2 }, { "cost": "58.27", "date": "2026-01-26T00:00:00.000Z", "event_count": 1 }, { "cost": "0.48", "date": "2026-01-27T00:00:00.000Z", "event_count": 1 } ], "key": "total", "label": "Total" } ] } } } }, "400": { "description": "Invalid request data. Ensure start_date and end_date are valid ISO 8601 dates and start_date is before end_date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/trend", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/trend", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update a key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/trend", "method": "GET" } } } } }, "404": { "description": "Dimension key not found for this organization. Verify dimension_key matches a dimension registered for your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Resource not found or not accessible with this API key. Check the identifier and try again.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Resource not found or not accessible with this API key. Check the identifier and try again.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/trend", "method": "GET" } } } } }, "429": { "description": "Rate limit exceeded. The general API tier allows 100 requests per 15 minutes; wait for the window to reset before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/cost-data/trend", "method": "GET" } } } } } }, "description": "Get cost trend over time\n\nReturns organization-wide time-series cost data. Can be filtered to one\nend user, filtered to one dimension value, or grouped by dimension.\n\n**Granularity** (not overridable): ranges up to 30 days return daily\npoints, 31 to 90 days weekly, over 90 days monthly.\n\n**Modes:**\n- No filter params: Returns a single \"Total\" series (all costs)\n- `dimension_key` only: Returns top 5 dimension values as series + \"Other\"\n- `dimension_key` + `dimension_value`: Returns a single series filtered to that value\n- `end_user_id`: Returns a single series for that end user\n\n`dimension_key` must be a dimension registered for your organization;\nunknown keys return 404. `dimension_value` is only honored together with\n`dimension_key`; if sent alone the parameter is ignored and the unfiltered\n\"Total\" series is returned. If `dimension_key` or `dimension_value` is\nprovided, `end_user_id` is ignored; do not combine them.\n\n**Required Scope:** `costs:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get organization-wide cost trend", "tags": [ "Cost Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Start of date range (ISO 8601, inclusive). Must be before end_date.", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } }, { "description": "Optional end user ID (UUID, as returned in /cost-data/by-end-user end_user_id) to filter the trend to one end user. Must be a UUID; the 'unassigned' bucket cannot be filtered here. Prefer GET /end-user-costs/{externalId}/trend for per-end-user analysis.", "in": "query", "name": "end_user_id", "required": false, "schema": { "type": "string" } }, { "description": "Optional dimension key to filter or group by. Must be a dimension registered for your organization; unknown keys return 404.", "in": "query", "name": "dimension_key", "required": false, "schema": { "type": "string" } }, { "description": "Optional dimension value to filter to. Only honored together with dimension_key; sent alone it is ignored and the unfiltered \"Total\" series is returned.", "in": "query", "name": "dimension_value", "required": false, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/attribution-data/by-dimension": { "get": { "operationId": "getAttributionDataByDimension", "responses": { "200": { "description": "Dimension cost breakdown retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributionDataCostBreakdownResponseDTO" }, "example": { "items": [ { "attribution_value": "gpt-4o", "cache_creation_cost": "0.5", "cache_creation_input_tokens": 133400, "cache_read_cost": "0.11", "cache_read_input_tokens": 220150, "event_count": 3, "input_cost": "5.39", "input_tokens": 2155500, "output_cost": "2.5", "output_tokens": 249300, "percent_of_total": 50, "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "8.5" }, { "attribution_value": "claude-sonnet-4-5", "cache_creation_cost": null, "cache_creation_input_tokens": null, "cache_read_cost": "0.09", "cache_read_input_tokens": 181400, "event_count": 2, "input_cost": "3.37", "input_tokens": 1348000, "output_cost": "1.64", "output_tokens": 163450, "percent_of_total": 30, "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "5.1" }, { "attribution_value": "gpt-4o-mini", "cache_creation_cost": null, "cache_creation_input_tokens": null, "cache_read_cost": "0.07", "cache_read_input_tokens": 140600, "event_count": 2, "input_cost": "2.23", "input_tokens": 891850, "output_cost": "1.1", "output_tokens": 109700, "percent_of_total": 20, "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "3.4" } ], "total_cost": "17" } } } }, "400": { "description": "Invalid request data. Check that start_date and end_date are valid ISO 8601 dates and fix the field named in error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/by-dimension", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/by-dimension", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update an API key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/by-dimension", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/by-dimension", "method": "GET" } } } } } }, "description": "Get cost breakdown by any dimension\n\nReturns cost aggregation grouped by any metadata dimension key.\nSupports any key: model, provider, feature, agent_id, workflow_id, or custom keys.\nEvents without the specified dimension key are bucketed as \"Unassigned\".\n\nWhen `format=csv`, the response is a `text/csv` attachment\n(`Content-Disposition: attachment; filename=\"bear-lumen-attribution---to-.csv\"`)\nwhose columns mirror the JSON item fields; null token counts and costs\nrender as empty cells, never 0. The JSON schema below applies only to\n`format=json` (the default).\n\n**Required Scope:** `costs:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get cost breakdown by dimension", "tags": [ "Attribution Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Metadata dimension key to group by (e.g., \"model\", \"provider\", \"agent_id\").", "in": "query", "name": "dimension", "required": true, "schema": { "type": "string" } }, { "description": "Start of date range (ISO 8601, inclusive).", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } }, { "description": "Optional cross-dimension filter key (e.g., \"environment\"). Applied only when filter_value is also provided; a request with filter_key alone returns the unfiltered breakdown.", "in": "query", "name": "filter_key", "required": false, "schema": { "type": "string" } }, { "description": "Optional cross-dimension filter value (exact match). Applied only when filter_key is also provided; a request with filter_value alone returns the unfiltered breakdown.", "in": "query", "name": "filter_value", "required": false, "schema": { "type": "string" } }, { "description": "Response format: json (default) or csv.", "in": "query", "name": "format", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } } ], "x-required-scopes": [ "costs:read" ] } }, "/attribution-data/dimension-values": { "get": { "operationId": "listAttributionDataDimensionValues", "responses": { "200": { "description": "Dimension values retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributionDataValuesResponseDTO" }, "example": { "values": [ "match-narration", "npc-dialogue", "quest-generation", "world-summary" ] } } } }, "400": { "description": "Invalid request data. Check that start_date and end_date are valid ISO 8601 dates and fix the field named in error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/dimension-values", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/dimension-values", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update an API key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/dimension-values", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/dimension-values", "method": "GET" } } } } } }, "description": "List unique values for any dimension\n\nReturns every distinct value of a metadata dimension key in the date\nrange, sorted alphabetically. Useful for populating filter dropdowns for\nany dimension. The response is not paginated; narrow the date range when\nlisting high-cardinality dimensions (e.g., session_id).\n\n**Required Scope:** `costs:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "List unique dimension values", "tags": [ "Attribution Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Metadata dimension key to list values for (e.g., \"model\", \"provider\").", "in": "query", "name": "dimension", "required": true, "schema": { "type": "string" } }, { "description": "Start of date range (ISO 8601, inclusive).", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/attribution-data/time-series": { "get": { "operationId": "getPublicAttributionTimeSeries", "responses": { "200": { "description": "Attribution time-series retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicAttributionTimeSeriesResponseDTO" }, "example": { "granularity": "daily", "series": [ { "data_points": [ { "date": "2026-02-05T00:00:00.000Z", "event_count": 1, "total_cost": "3.02" }, { "date": "2026-02-06T00:00:00.000Z", "event_count": 1, "total_cost": "4.78" }, { "date": "2026-02-07T00:00:00.000Z", "event_count": 1, "total_cost": "8.2" } ], "key": "quest-generation", "label": "quest-generation" }, { "data_points": [ { "date": "2026-02-03T00:00:00.000Z", "event_count": 2, "total_cost": "6.34" }, { "date": "2026-02-04T00:00:00.000Z", "event_count": 1, "total_cost": "2.16" } ], "key": "match-narration", "label": "match-narration" }, { "data_points": [ { "date": "2026-02-03T00:00:00.000Z", "event_count": 1, "total_cost": "2.66" }, { "date": "2026-02-04T00:00:00.000Z", "event_count": 1, "total_cost": "2.44" }, { "date": "2026-02-05T00:00:00.000Z", "event_count": 1, "total_cost": "2.9" } ], "key": "npc-dialogue", "label": "npc-dialogue" }, { "data_points": [ { "date": "2026-02-03T00:00:00.000Z", "event_count": 1, "total_cost": "1.4" }, { "date": "2026-02-04T00:00:00.000Z", "event_count": 1, "total_cost": "2" }, { "date": "2026-02-06T00:00:00.000Z", "event_count": 1, "total_cost": "2.1" }, { "date": "2026-02-07T00:00:00.000Z", "event_count": 1, "total_cost": "2" } ], "key": "world-summary", "label": "world-summary" } ] } } } }, "400": { "description": "Invalid request data. Check that start_date and end_date are valid ISO 8601 dates and fix the field named in error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/time-series", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/time-series", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update an API key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/time-series", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/time-series", "method": "GET" } } } } } }, "description": "Get attribution time-series\n\nReturns time-bucketed multi-series cost data grouped by any metadata dimension key.\nGranularity is chosen from the date range: daily for ranges up to 30 days,\nweekly up to 90 days, monthly beyond. The five highest-cost dimension\nvalues each get their own series; when more than five values exist, the\nremaining values are aggregated into an extra series with key \"other\" and\nlabel \"Other\".\n\n**Required Scope:** `costs:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get attribution time-series", "tags": [ "Attribution Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Metadata dimension key to group by (e.g., \"model\", \"provider\", \"agent_id\").", "in": "query", "name": "dimension", "required": true, "schema": { "type": "string" } }, { "description": "Start of date range (ISO 8601, inclusive).", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } }, { "description": "Optional cross-dimension filter key (e.g., \"environment\"). Applied only when filter_value is also provided; a request with filter_key alone returns the unfiltered series.", "in": "query", "name": "filter_key", "required": false, "schema": { "type": "string" } }, { "description": "Optional cross-dimension filter value (exact match). Applied only when filter_key is also provided; a request with filter_value alone returns the unfiltered series.", "in": "query", "name": "filter_value", "required": false, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/attribution-data/dimension-keys": { "get": { "operationId": "listPublicAttributionDimensionKeys", "responses": { "200": { "description": "Dimension keys retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicAttributionDimensionKeysResponseDTO" }, "example": { "keys": [ "agent_id", "feature", "game_mode", "model", "provider", "region", "session_id", "session_type", "workflow_id" ] } } } }, "400": { "description": "Invalid request data. Check that start_date and end_date are valid ISO 8601 dates and fix the field named in error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/dimension-keys", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/dimension-keys", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update an API key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/dimension-keys", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/dimension-keys", "method": "GET" } } } } } }, "description": "List distinct dimension keys\n\nReturns every distinct metadata dimension key from usage events within a\ndate range, sorted alphabetically. Enables dynamic population of dimension\nselectors. The response is not paginated.\n\n**Required Scope:** `costs:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "List distinct dimension keys", "tags": [ "Attribution Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Start of date range (ISO 8601, inclusive).", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/attribution-data/sessions": { "get": { "operationId": "getAttributionDataSessionBreakdown", "responses": { "200": { "description": "Session cost breakdown retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributionDataSessionCostBreakdownResponseDTO" }, "example": { "sessions": [ { "event_count": 4, "session_id": "sess_mQ4vX8kN", "session_type": "multiplayer", "total_cost": "10.4" }, { "event_count": 3, "session_id": "sess_tR7pW2jD", "session_type": "multiplayer", "total_cost": "6.6" } ], "summary": { "avg_cost_per_session": "8.5", "total_sessions": 2 } } } } }, "400": { "description": "Invalid request data. Check that start_date and end_date are valid ISO 8601 dates and fix the field named in error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/sessions", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/sessions", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update an API key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/sessions", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/sessions", "method": "GET" } } } } } }, "description": "Get session cost breakdown\n\nReturns per-session cost totals, ordered by total cost descending.\n\nInclude `session_id` on your usage events to group them into sessions;\noptionally include `session_type` (any string label, e.g.,\n\"support-agent\", \"batch-summarizer\"). Events without `session_id` are\nexcluded. Events without `session_type` appear here with `session_type`\n\"unknown\".\n\nThe `summary` object reflects only the sessions returned in this response\n(after limit/offset), not the full date range. There is no range-wide\ntotal; page until fewer than `limit` sessions are returned.\n\n**Required Scope:** `costs:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get session cost breakdown", "tags": [ "Attribution Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Start of date range (ISO 8601, inclusive). If start_date is not before end_date the response is empty rather than an error.", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } }, { "description": "Exact-match filter on the session_type value (e.g., \"support-agent\").", "in": "query", "name": "session_type", "required": false, "schema": { "type": "string" } }, { "description": "Maximum sessions to return, ordered by total cost descending (default 100).", "in": "query", "name": "limit", "required": false, "schema": { "format": "double", "type": "number" } }, { "description": "Number of sessions to skip for pagination (default 0).", "in": "query", "name": "offset", "required": false, "schema": { "format": "double", "type": "number" } } ], "x-required-scopes": [ "costs:read" ] } }, "/attribution-data/session-comparison": { "get": { "operationId": "compareAttributionDataSessionTypes", "responses": { "200": { "description": "Session type comparison retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributionDataSessionTypeComparisonResponseDTO" }, "example": { "cost_efficiency_ratio": 1.328125, "savings_percent": -32.8125, "segments": [ { "avg_cost_per_session": "8.5", "session_count": 2, "session_type": "multiplayer", "total_cost": "17", "total_event_count": 7 }, { "avg_cost_per_session": "6.4", "session_count": 2, "session_type": "singleplayer", "total_cost": "12.8", "total_event_count": 4 } ] } } } }, "400": { "description": "Invalid request data. Check that start_date and end_date are valid ISO 8601 dates and fix the field named in error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/session-comparison", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/session-comparison", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update an API key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/session-comparison", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/session-comparison", "method": "GET" } } } } } }, "description": "Compare session types\n\nReturns a per-session-type cost comparison with a cost efficiency ratio.\n`cost_efficiency_ratio` is the weighted average cost per session of the\nnon-\"singleplayer\" segments divided by the \"singleplayer\" segment's\naverage cost per session, so values below 1 mean those sessions cost less\non average. `savings_percent` is (1 - cost_efficiency_ratio) * 100. Both\nare null when the range lacks a \"singleplayer\" segment, lacks any other\nsegment, or the \"singleplayer\" average cost per session is zero.\n\nInclude `session_id` on your usage events to group them into sessions;\noptionally include `session_type` (any string label). Events without\n`session_id` are excluded, and events without `session_type` are excluded\nfrom this comparison entirely.\n\n**Required Scope:** `costs:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Compare session types", "tags": [ "Attribution Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Start of date range (ISO 8601, inclusive). If start_date is not before end_date the response is empty rather than an error.", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/attribution-data/sessions/{sessionId}": { "get": { "operationId": "getAttributionDataSessionDetail", "responses": { "200": { "description": "Session detail retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributionDataSessionDetailResponseDTO" }, "example": { "features": [ { "event_count": 2, "feature": "match-narration", "total_cost": "6.34" }, { "event_count": 1, "feature": "npc-dialogue", "total_cost": "2.66" }, { "event_count": 1, "feature": "world-summary", "total_cost": "1.4" } ], "session_id": "sess_mQ4vX8kN", "session_type": "multiplayer", "total_cost": "10.4" } } } }, "400": { "description": "Invalid request data. Fix the field named in error.message and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/sessions/{sessionId}", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/sessions/{sessionId}", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update an API key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/sessions/{sessionId}", "method": "GET" } } } } }, "404": { "description": "No session with this sessionId exists for your organization. Verify the session_id metadata value sent on your usage events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Resource not found or not accessible with this API key. Check the identifier and try again.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Resource not found or not accessible with this API key. Check the identifier and try again.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/sessions/{sessionId}", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/sessions/{sessionId}", "method": "GET" } } } } } }, "description": "Get session detail\n\nReturns a per-feature cost breakdown for one session. Unlike the other\nattribution endpoints, the lookup spans all time; it is not bounded by a\ndate range. Events without a feature are grouped under \"unknown\".\n\nInclude `session_id` on your usage events to group them into sessions;\noptionally include `session_type` (any string label).\n\n**Required Scope:** `costs:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get session detail", "tags": [ "Attribution Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "The session_id metadata value to look up.", "in": "path", "name": "sessionId", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/attribution-data/sessions/{sessionId}/tree": { "get": { "operationId": "getAttributionDataSessionTree", "responses": { "200": { "description": "Session call tree retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributionDataSessionTreeResponseDTO" }, "example": { "roots": [ { "agent_id": null, "children": [ { "agent_id": null, "children": [], "depth": 1, "event_count": 1, "kind": "retrieval", "name": "kb-search", "orphaned": false, "own_cost": "0.84", "parent_span_id": "a3f81c92d4b7e615", "span_id": "b6d24e07f9a1c382", "subtree_cost": "0.84" } ], "depth": 0, "event_count": 1, "kind": "agent", "name": "resolve-ticket", "orphaned": false, "own_cost": "1.13", "parent_span_id": null, "span_id": "a3f81c92d4b7e615", "subtree_cost": "1.97" } ], "session_id": "sess_out_qW3nT8xA", "untraced": { "event_count": 1, "total_cost": "0.28" } } } } }, "400": { "description": "Invalid request data. Fix the field named in error.message and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/sessions/{sessionId}/tree", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/sessions/{sessionId}/tree", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update an API key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/sessions/{sessionId}/tree", "method": "GET" } } } } }, "404": { "description": "No session with this sessionId exists for your organization. Verify the session_id value sent on your usage events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "NOT_FOUND", "message": "Resource not found or not accessible with this API key. Check the identifier and try again.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Resource not found or not accessible with this API key. Check the identifier and try again.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/sessions/{sessionId}/tree", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/sessions/{sessionId}/tree", "method": "GET" } } } } } }, "description": "Get session call tree\n\nReconstructs one session's span call tree: one node per span with its\nown cost, its subtree cost (the span plus every descendant), and its\nnested children, so you can see which branch of a multi-agent run spent\nthe money. Roots are ordered by subtree cost descending. Unlike the\nother attribution endpoints, the lookup spans all time; it is not\nbounded by a date range.\n\nUse spans (see the tracing guide) to link calls into a tree; events\nthat carry the session_id but no span_id are reported in the untraced\nbucket rather than as tree nodes. The sum of the root subtree costs\nplus the untraced total always equals the session's flat total from the\nsessions endpoints.\n\nMalformed span chains never lose cost: a span whose parent id does not\nexist in the session is promoted to a root and flagged orphaned; a\nparent-pointer cycle is broken at a deterministic entry span flagged\ncycle; chains deeper than 32 levels are cut at a node flagged\ndepth_capped, which keeps the pruned descendants' cost in its subtree\ncost.\n\n**Required Scope:** `costs:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get session call tree", "tags": [ "Attribution Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "The session_id metadata value to look up.", "in": "path", "name": "sessionId", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/attribution-data/by-outcome": { "get": { "operationId": "getAttributionDataByOutcome", "responses": { "200": { "description": "Outcome cost breakdown retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributionDataOutcomeBreakdownResponseDTO" }, "example": { "items": [ { "completed_cost": "4.46", "completed_count": 2, "cost_per_completed_unit": "2.23", "failed_cost": "0.78", "failed_count": 1, "outcome": "ticket_resolved", "retried_unit_count": 1, "unresolved_cost": "0.75", "unresolved_count": 1 } ], "total_outcome_count": 1 } } } }, "400": { "description": "Invalid request data. Check that start_date is before end_date, both are valid ISO 8601 dates, and unresolved_after_hours is a whole number between 1 and 8760.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/by-outcome", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/by-outcome", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update an API key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/by-outcome", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/by-outcome", "method": "GET" } } } } } }, "description": "Get cost per declared outcome\n\nReturns the true cost per unit of value: for every outcome your spans\ndeclare (see the tracing guide), completed, failed, and unresolved units\nside by side. Use this to price against real unit economics; the cost of\nruns that failed stays visible as its own line instead of inflating the\ncompleted average.\n\nA unit is one execution of an outcome-declaring span. Its cost is the\nfull cost of that span's call subtree, plus the session's untraced\nevents when the outcome span is the session's only root span. Retried\nunits (same unit_key across attempts) count once while their cost sums\nacross attempts; retried_unit_count reports how many units needed more\nthan one attempt.\n\nThe date range filters on when a unit RESOLVED (its completion or\nfailure event), or on last activity for unresolved units, so a unit's\ncost may predate the range. Units that declared an outcome, never\nresolved, and have been inactive longer than unresolved_after_hours are\nreported as unresolved; terminal-less units younger than that threshold\nare treated as still running and excluded.\n\n**Required Scope:** `costs:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get cost per declared outcome", "tags": [ "Attribution Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Start of date range (ISO 8601, inclusive). Applies to unit resolution time, not to when the cost was incurred.", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } }, { "description": "Hours of inactivity after which a terminal-less unit is reported as unresolved rather than still running. Whole number between 1 and 8760; default 24.", "in": "query", "name": "unresolved_after_hours", "required": false, "schema": { "format": "double", "type": "number" } } ], "x-required-scopes": [ "costs:read" ] } }, "/attribution-data/by-agent": { "get": { "operationId": "getAttributionDataByAgent", "responses": { "200": { "description": "Agent cost breakdown retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributionDataCostBreakdownResponseDTO" }, "example": { "items": [ { "attribution_value": "quest-writer", "cache_creation_cost": null, "cache_creation_input_tokens": null, "cache_read_cost": null, "cache_read_input_tokens": null, "event_count": 3, "input_cost": "9.09", "input_tokens": 3636900, "output_cost": "4.59", "output_tokens": 459700, "percent_of_total": 40, "reasoning_cost": "2.32", "reasoning_tokens": 231900, "total_cost": "16" }, { "attribution_value": "match-caster", "cache_creation_cost": "0.5", "cache_creation_input_tokens": 133400, "cache_read_cost": "0.18", "cache_read_input_tokens": 360750, "event_count": 6, "input_cost": "9.01", "input_tokens": 3603650, "output_cost": "4.31", "output_tokens": 429650, "percent_of_total": 35, "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "14" }, { "attribution_value": "npc-brain", "cache_creation_cost": null, "cache_creation_input_tokens": null, "cache_read_cost": "0.09", "cache_read_input_tokens": 181400, "event_count": 3, "input_cost": "5.31", "input_tokens": 2122500, "output_cost": "2.6", "output_tokens": 259350, "percent_of_total": 20, "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "8" }, { "attribution_value": "Unassigned", "cache_creation_cost": null, "cache_creation_input_tokens": null, "cache_read_cost": null, "cache_read_input_tokens": null, "event_count": 1, "input_cost": "1.34", "input_tokens": 534900, "output_cost": "0.66", "output_tokens": 66200, "percent_of_total": 5, "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "2" } ], "total_cost": "40" } } } }, "400": { "description": "Invalid request data. Check that start_date and end_date are valid ISO 8601 dates and fix the field named in error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/by-agent", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/by-agent", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update an API key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/by-agent", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/by-agent", "method": "GET" } } } } } }, "description": "Get cost breakdown by agent\n\nReturns cost aggregation grouped by agent_id from usage event metadata.\nEvents without an agent_id are bucketed as \"Unassigned\".\nConvenience shortcut for GET /attribution-data/by-dimension with\ndimension=agent_id. Use by-dimension when you need cross-dimension\nfiltering (filter_key/filter_value) or CSV export.\n\n**Required Scope:** `costs:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get cost breakdown by agent", "tags": [ "Attribution Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Start of date range (ISO 8601, inclusive).", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/attribution-data/by-workflow": { "get": { "operationId": "getAttributionDataByWorkflow", "responses": { "200": { "description": "Workflow cost breakdown retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributionDataCostBreakdownResponseDTO" }, "example": { "items": [ { "attribution_value": "live-match-flow", "cache_creation_cost": "0.5", "cache_creation_input_tokens": 133400, "cache_read_cost": "0.27", "cache_read_input_tokens": 542150, "event_count": 7, "input_cost": "10.99", "input_tokens": 4395350, "output_cost": "5.24", "output_tokens": 522450, "percent_of_total": 42.5, "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "17" }, { "attribution_value": "solo-campaign-flow", "cache_creation_cost": null, "cache_creation_input_tokens": null, "cache_read_cost": null, "cache_read_input_tokens": null, "event_count": 4, "input_cost": "7.76", "input_tokens": 3103500, "output_cost": "3.9", "output_tokens": 389850, "percent_of_total": 32, "reasoning_cost": "1.14", "reasoning_tokens": 113600, "total_cost": "12.8" }, { "attribution_value": "content-batch-flow", "cache_creation_cost": null, "cache_creation_input_tokens": null, "cache_read_cost": null, "cache_read_input_tokens": null, "event_count": 1, "input_cost": "4.66", "input_tokens": 1864200, "output_cost": "2.36", "output_tokens": 236400, "percent_of_total": 20.5, "reasoning_cost": "1.18", "reasoning_tokens": 118300, "total_cost": "8.2" }, { "attribution_value": "Unassigned", "cache_creation_cost": null, "cache_creation_input_tokens": null, "cache_read_cost": null, "cache_read_input_tokens": null, "event_count": 1, "input_cost": "1.34", "input_tokens": 534900, "output_cost": "0.66", "output_tokens": 66200, "percent_of_total": 5, "reasoning_cost": null, "reasoning_tokens": null, "total_cost": "2" } ], "total_cost": "40" } } } }, "400": { "description": "Invalid request data. Check that start_date and end_date are valid ISO 8601 dates and fix the field named in error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/by-workflow", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/by-workflow", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update an API key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/by-workflow", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/by-workflow", "method": "GET" } } } } } }, "description": "Get cost breakdown by workflow\n\nReturns cost aggregation grouped by workflow_id from usage event metadata.\nEvents without a workflow_id are bucketed as \"Unassigned\".\nConvenience shortcut for GET /attribution-data/by-dimension with\ndimension=workflow_id. Use by-dimension when you need cross-dimension\nfiltering (filter_key/filter_value) or CSV export.\n\n**Required Scope:** `costs:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Get cost breakdown by workflow", "tags": [ "Attribution Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Start of date range (ISO 8601, inclusive).", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/attribution-data/agents": { "get": { "operationId": "listAttributionDataAgents", "responses": { "200": { "description": "Agent list retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributionDataValuesResponseDTO" }, "example": { "values": [ "match-caster", "npc-brain", "quest-writer" ] } } } }, "400": { "description": "Invalid request data. Check that start_date and end_date are valid ISO 8601 dates and fix the field named in error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/agents", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/agents", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update an API key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/agents", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/agents", "method": "GET" } } } } } }, "description": "List unique agent identifiers\n\nReturns every distinct agent_id value from usage event metadata for the\ngiven date range, sorted alphabetically. Useful for populating agent\nfilter dropdowns. The response is not paginated.\nConvenience shortcut for GET /attribution-data/dimension-values with\ndimension=agent_id.\n\n**Required Scope:** `costs:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "List unique agent IDs", "tags": [ "Attribution Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Start of date range (ISO 8601, inclusive).", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/attribution-data/workflows": { "get": { "operationId": "listAttributionDataWorkflows", "responses": { "200": { "description": "Workflow list retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributionDataValuesResponseDTO" }, "example": { "values": [ "content-batch-flow", "live-match-flow", "solo-campaign-flow" ] } } } }, "400": { "description": "Invalid request data. Check that start_date and end_date are valid ISO 8601 dates and fix the field named in error.message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/workflows", "method": "GET" } } } } }, "401": { "description": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/workflows", "method": "GET" } } } } }, "403": { "description": "API key lacks the costs:read scope. Create or update an API key with the costs:read scope, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/workflows", "method": "GET" } } } } }, "429": { "description": "Rate limit or plan quota exceeded. Slow down and retry after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/attribution-data/workflows", "method": "GET" } } } } } }, "description": "List unique workflow identifiers\n\nReturns every distinct workflow_id value from usage event metadata for\nthe given date range, sorted alphabetically. Useful for populating\nworkflow filter dropdowns. The response is not paginated.\nConvenience shortcut for GET /attribution-data/dimension-values with\ndimension=workflow_id.\n\n**Required Scope:** `costs:read`.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "List unique workflow IDs", "tags": [ "Attribution Data API" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "Start of date range (ISO 8601, inclusive).", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string" } }, { "description": "End of date range (ISO 8601, exclusive).", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string" } } ], "x-required-scopes": [ "costs:read" ] } }, "/usage-events": { "post": { "operationId": "ingestUsageEvent", "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageEventResponse" }, "example": { "event_id": "166a63b3-5388-5423-8f3f-d6508823557f", "message": "Event accepted for processing", "status": "accepted" } } } }, "400": { "description": "Invalid request data. error.message names the failing field and the constraint to satisfy before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage-events", "method": "POST" } } } } }, "401": { "description": "Authentication failed. Check your Authorization: Bearer API key and the X-Signature and X-Timestamp headers. API key failures return the standard error envelope; HMAC signature verification failures return a flat { \"error\": string, \"code\": string } body instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage-events", "method": "POST" } } } } }, "403": { "description": "Insufficient permissions. Use an API key that has the usage:write scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage-events", "method": "POST" } } } } }, "429": { "description": "Plan event quota exceeded. Includes X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After (seconds until the next period) headers; back off until Retry-After elapses or upgrade your plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage-events", "method": "POST" } } } } } }, "description": "Ingest a usage event\n\nRecords an AI usage event for cost calculation. Events are processed\nasynchronously; this endpoint returns immediately with 202 Accepted.\nAccepted events are queued for cost calculation and appear in the cost\nand attribution analytics endpoints once processing completes, typically\nshortly after ingestion.\n\nThis endpoint requires HMAC request signing (X-Signature and X-Timestamp\nheaders) in addition to your API key, and retries are safe because events\nare deduplicated by their idempotency_key. See the Request signing (HMAC)\nand Idempotency sections of this reference for the full details.\n\nAttribution works in three layers: your organization is identified\nimplicitly by the API key, so there is no customer_id field to send. Your\nown end users are attributed with the optional user_id field, and any\nother attribute you care about (team, tenant, environment) goes in\nmetadata. After a 202, confirm the event landed with GET /usage/events;\ncost figures appear in the cost-data endpoints once processing completes.\n\n**Required Scope:** `usage:write`.\n\n**Flagged events:** status \"accepted_flagged\" means the event was\naccepted and will be processed, but needs attention. Causes: timestamp\nmore than 24 hours old, timestamp more than 1 minute in the future, plan\nevent quota soft limit reached, or (when no cost_override is\nsupplied) no rate card configured for the model, in which case cost\ncannot be calculated until a rate card exists. flag_reason states the\nspecific cause.\n\nWhen your plan quota passes its soft limit, 202 responses include an\nX-BearLumen-Usage-Warning header.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Ingest a usage event", "tags": [ "Usage Events" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "HMAC signature of this request in the form v1={hex}; see HMAC signing above. Requests without a valid signature are rejected with 401.", "in": "header", "name": "x-signature", "required": false, "schema": { "type": "string" } }, { "description": "Unix timestamp (in seconds) used in the signed payload; timestamps more than 5 minutes from server time are rejected with 401.", "in": "header", "name": "x-timestamp", "required": false, "schema": { "type": "string" } } ], "requestBody": { "description": "Usage event data.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageEventRequest", "description": "Usage event data." }, "example": { "idempotency_key": "3f9a2b1c-8d7e-4f6a-9b2c-1a2b3c4d5e6f", "model": "gpt-4o", "input_tokens": 1500, "output_tokens": 420, "event_invoked_at": "2026-01-15T10:30:00.000Z", "user_id": "user_123", "provider": "openai", "feature": "chat" } } } }, "x-required-scopes": [ "usage:write" ] } }, "/usage-events/batch": { "post": { "operationId": "ingestUsageEventBatch", "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageEventBatchResponse" }, "example": { "accepted": 2, "failed": 1, "results": [ { "event_id": "7372eff3-6ad4-51e1-9be5-539a62e63e79", "index": 0, "message": "Event accepted for processing", "status": "accepted" }, { "event_id": "70cd7d44-3f86-535a-8c55-5f80f202e234", "index": 1, "message": "Event accepted for processing", "status": "accepted" }, { "error": "event_invoked_at must be a valid ISO 8601 date", "index": 2, "message": "event_invoked_at must be a valid ISO 8601 date", "status": "rejected" } ] } } } }, "400": { "description": "Invalid request data (for example an empty batch or more than 100 events). error.message names the failing field and the constraint to satisfy before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed: one or more fields are missing or invalid.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Request validation failed: one or more fields are missing or invalid.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage-events/batch", "method": "POST" } } } } }, "401": { "description": "Authentication failed. Check your Authorization: Bearer API key and the X-Signature and X-Timestamp headers. API key failures return the standard error envelope; HMAC signature verification failures return a flat { \"error\": string, \"code\": string } body instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage-events/batch", "method": "POST" } } } } }, "403": { "description": "Insufficient permissions. Use an API key that has the usage:write scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "FORBIDDEN", "message": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "The API key is missing the required scope for this endpoint. Create or update a key with that scope.", "retryable": false } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage-events/batch", "method": "POST" } } } } }, "429": { "description": "API rate limit exceeded. Slow down and retry after the current window resets. Plan event quota exhaustion on this endpoint never returns a batch-level 429; it surfaces as per-item rejections inside the 202 response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorEnvelopeDTO" }, "example": { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded. Slow down and retry after the current window resets.", "correlationId": "OLIVE-DINOSAUR-1b2fE4", "referenceCode": "OLIVE-DINOSAUR-1b2fE4", "details": { "userMessage": "Too many requests. Please wait a moment before trying again.", "retryable": true } }, "meta": { "timestamp": "2026-07-08T12:34:56.789Z", "requestId": "req_a1b2c3d4e5f6", "path": "/v1/usage-events/batch", "method": "POST" } } } } } }, "description": "Ingest a batch of usage events\n\nAccepts an array of 1 to 100 usage events for cost calculation. Each\nevent is processed independently (partial success). A rejected item may\nbe caused by validation failure, plan event quota exhaustion, or an\nunexpected processing error. The batch request itself returns 202 even\nwhen every item is rejected; plan quota exhaustion never produces a\nbatch-level 429 and instead appears as per-item rejections, so inspect\nresults[].status and the accepted/failed counters. Accepted events are\nqueued for cost calculation and appear in the cost and attribution\nanalytics endpoints once processing completes, typically shortly after\ningestion.\n\nThis endpoint requires HMAC request signing (X-Signature and X-Timestamp\nheaders) in addition to your API key, and retries are safe because events\nare deduplicated by their idempotency_key. See the Request signing (HMAC)\nand Idempotency sections of this reference for the full details.\n\n**Required Scope:** `usage:write`.\n\n**Flagged events:** status \"accepted_flagged\" means the event was\naccepted and will be processed, but needs attention. Causes: timestamp\nmore than 24 hours old, timestamp more than 1 minute in the future, plan\nevent quota soft limit reached, or (when no cost_override is\nsupplied) no rate card configured for the model, in which case cost\ncannot be calculated until a rate card exists. flag_reason states the\nspecific cause.\n\nWhen your plan quota passes its soft limit, batch items are accepted\nwith status \"accepted_flagged\" and a flag_reason naming the limit; the\nX-BearLumen-Usage-Warning header is emitted only by the single-event\nendpoint.\n\nRequests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.", "summary": "Ingest a batch of usage events", "tags": [ "Usage Events" ], "security": [ { "apiKey": [] } ], "parameters": [ { "description": "HMAC signature of this request in the form v1={hex}; see HMAC signing above. Requests without a valid signature are rejected with 401.", "in": "header", "name": "x-signature", "required": false, "schema": { "type": "string" } }, { "description": "Unix timestamp (in seconds) used in the signed payload; timestamps more than 5 minutes from server time are rejected with 401.", "in": "header", "name": "x-timestamp", "required": false, "schema": { "type": "string" } } ], "requestBody": { "description": "Batch of usage events.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageEventBatchRequest", "description": "Batch of usage events." } } } }, "x-required-scopes": [ "usage:write" ] } } }, "servers": [ { "url": "https://api.bearlumen.com/v1", "description": "Production server." } ], "tags": [ { "name": "Connectivity", "description": "Connectivity check to verify your API key is valid and confirm the organization it is scoped to before you integrate." }, { "name": "Usage Events", "description": "AI usage event ingestion (single and batch) for cost tracking and attribution." }, { "name": "Usage Tracking", "description": "Usage event recording plus historical query and aggregation endpoints." }, { "name": "Cost Data API", "description": "Organization-level cost summaries, breakdowns, and trend data across all AI providers." }, { "name": "End User Costs API", "description": "Per-user cost analysis scoped by your external user ID. Understand spend concentration and per-customer unit economics." }, { "name": "Margin Data API", "description": "Margin and profitability analysis comparing AI costs against revenue." }, { "name": "Attribution Data API", "description": "Dimensional cost analysis grouped by model, provider, feature, agent, or workflow." }, { "name": "Dimension Data API", "description": "Custom dimension definitions and cost breakdowns by user-defined categories." }, { "name": "Rate Cards API", "description": "Effective per-model rates for client-side cost estimation. The SDK budget feature refreshes its local price table from here; the server-side ledger is the record." }, { "name": "Insights API", "description": "AI-optimized statistical summary: period-over-period totals, distributions, top movers, and correlations." } ], "x-tagGroups": [ { "name": "Getting Started", "tags": [ "Connectivity" ] }, { "name": "Usage Ingestion", "tags": [ "Usage Events", "Usage Tracking" ] }, { "name": "Cost Intelligence", "tags": [ "Cost Data API", "End User Costs API", "Margin Data API", "Attribution Data API", "Dimension Data API", "Rate Cards API" ] }, { "name": "Insights", "tags": [ "Insights API" ] } ], "externalDocs": { "url": "https://docs.bearlumen.com", "description": "Bear Lumen documentation." } }