> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/api-reference/readme/platform/billing.md).

# Billing

## Get workspace LLM usage

> Return customer-visible LLM usage for an inclusive date range from one complete published calculation. Omit \`group\_by\` for totals, daily usage, attribution, and service breakdowns; use \`group\_by=model\` or \`group\_by=class\` for those breakdowns. The optional \`service\_id\` filter is applied before aggregation.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"UsageResponse":{"anyOf":[{"$ref":"#/components/schemas/UsageOverviewResponse"},{"$ref":"#/components/schemas/UsageModelsResponse"},{"$ref":"#/components/schemas/UsageClassesResponse"}]},"UsageOverviewResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace whose usage or cost is reported."},"period":{"$ref":"#/components/schemas/Period","description":"Inclusive requested date range."},"calculation_run_id":{"type":"string","format":"uuid","title":"Calculation Run Id","description":"Immutable published calculation run selected for the entire range."},"attribution":{"$ref":"#/components/schemas/UsageAttribution"},"totals":{"$ref":"#/components/schemas/UsageTotals"},"daily":{"items":{"$ref":"#/components/schemas/DailyUsage"},"type":"array","title":"Daily","description":"Daily usage ordered from oldest to newest."},"services":{"items":{"$ref":"#/components/schemas/ServiceUsage"},"type":"array","title":"Services","description":"Services ordered by descending input-token usage."}},"type":"object","required":["workspace_id","period","calculation_run_id","attribution","totals","daily","services"],"title":"UsageOverviewResponse","description":"Usage overview returned when `group_by` is omitted."},"Period":{"properties":{"start_date":{"type":"string","format":"date","title":"Start Date"},"end_date":{"type":"string","format":"date","title":"End Date"}},"type":"object","required":["start_date","end_date"],"title":"Period","description":"Inclusive calendar-date range covered by the report."},"UsageAttribution":{"properties":{"conversation_attribution_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Conversation Attribution Rate","description":"Linked requests divided by all requests; null when there are no requests."},"service_attribution_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Service Attribution Rate","description":"Service-attributed input tokens divided by all input tokens; null when there are none."}},"type":"object","required":["conversation_attribution_rate","service_attribution_rate"],"title":"UsageAttribution","description":"Coverage of conversation and service attribution."},"UsageTotals":{"properties":{"conversation_count":{"type":"integer","title":"Conversation Count"},"request_count":{"type":"integer","title":"Request Count"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"},"has_unpriced_usage":{"type":"boolean","title":"Has Unpriced Usage","description":"Whether any usage in the period could not be priced."},"unpriced_tokens":{"type":"integer","title":"Unpriced Tokens","description":"Tokens excluded from calculated cost because no rate applied."}},"type":"object","required":["conversation_count","request_count","uncached_input_tokens","cached_input_tokens","output_tokens","has_unpriced_usage","unpriced_tokens"],"title":"UsageTotals","description":"Workspace totals for the requested period."},"DailyUsage":{"properties":{"usage_date":{"type":"string","format":"date","title":"Usage Date"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"}},"type":"object","required":["usage_date","uncached_input_tokens","cached_input_tokens","output_tokens"],"title":"DailyUsage","description":"Token usage for one calendar date."},"ServiceUsage":{"properties":{"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id","description":"Service identifier, or null for usage that could not be attributed."},"conversation_count":{"type":"integer","title":"Conversation Count"},"request_count":{"type":"integer","title":"Request Count"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"}},"type":"object","required":["service_id","conversation_count","request_count","uncached_input_tokens","cached_input_tokens","output_tokens"],"title":"ServiceUsage","description":"Usage attributed to one service."},"UsageModelsResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace whose usage or cost is reported."},"period":{"$ref":"#/components/schemas/Period","description":"Inclusive requested date range."},"calculation_run_id":{"type":"string","format":"uuid","title":"Calculation Run Id","description":"Immutable published calculation run selected for the entire range."},"models":{"items":{"$ref":"#/components/schemas/ModelUsage"},"type":"array","title":"Models"}},"type":"object","required":["workspace_id","period","calculation_run_id","models"],"title":"UsageModelsResponse","description":"Usage grouped by model, returned for `group_by=model`."},"ModelUsage":{"properties":{"model_id":{"type":"string","title":"Model Id"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider"},"request_count":{"type":"integer","title":"Request Count"},"calls_per_conversation":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Calls Per Conversation","description":"This model's linked requests / its distinct linked conversations in the selected scope; null if none."},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"}},"type":"object","required":["model_id","provider","request_count","calls_per_conversation","uncached_input_tokens","cached_input_tokens","output_tokens"],"title":"ModelUsage","description":"Usage attributed to one model and provider."},"UsageClassesResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace whose usage or cost is reported."},"period":{"$ref":"#/components/schemas/Period","description":"Inclusive requested date range."},"calculation_run_id":{"type":"string","format":"uuid","title":"Calculation Run Id","description":"Immutable published calculation run selected for the entire range."},"classes":{"items":{"$ref":"#/components/schemas/ClassUsage"},"type":"array","title":"Classes","description":"All recorded usage classes, including production and non-production, after any service filter."}},"type":"object","required":["workspace_id","period","calculation_run_id","classes"],"title":"UsageClassesResponse","description":"Usage grouped by usage class, returned for `group_by=class`."},"ClassUsage":{"properties":{"usage_class":{"type":"string","title":"Usage Class"},"conversation_count":{"type":"integer","title":"Conversation Count"},"request_count":{"type":"integer","title":"Request Count"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"}},"type":"object","required":["usage_class","conversation_count","request_count","uncached_input_tokens","cached_input_tokens","output_tokens"],"title":"ClassUsage","description":"Usage attributed to one usage class."}}},"paths":{"/v1/{workspace_id}/usage":{"get":{"tags":["Billing"],"summary":"Get workspace LLM usage","description":"Return customer-visible LLM usage for an inclusive date range from one complete published calculation. Omit `group_by` for totals, daily usage, attribution, and service breakdowns; use `group_by=model` or `group_by=class` for those breakdowns. The optional `service_id` filter is applied before aggregation.","operationId":"get-workspace-usage","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"start_date","in":"query","required":true,"schema":{"type":"string","format":"date","description":"First usage date to include.","title":"Start Date"},"description":"First usage date to include."},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","format":"date","description":"Last usage date to include. It cannot be in the future.","title":"End Date"},"description":"Last usage date to include. It cannot be in the future."},{"name":"service_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Limit the report to usage attributed to this service.","title":"Service Id"},"description":"Limit the report to usage attributed to this service."},{"name":"group_by","in":"query","required":false,"schema":{"anyOf":[{"enum":["model","class"],"type":"string"},{"type":"null"}],"description":"Return model or usage-class breakdowns instead of the overview.","title":"Group By"},"description":"Return model or usage-class breakdowns instead of the overview."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"401":{"description":"Missing or invalid authentication credentials."},"403":{"description":"Caller cannot access this workspace or lacks Data.view permission."},"404":{"description":"Workspace not found."},"410":{"description":"Workspace is archived."},"422":{"description":"Query validation failed: dates must be valid, `end_date` cannot be in the future, `start_date` must not follow `end_date`, and `group_by` must be supported."},"429":{"description":"Read rate limit exceeded."},"503":{"description":"The service or billing data is unavailable, or no complete calculation covers the period."}}}}}}
```

## Get workspace LLM cost

> Return Amigo-admin-only LLM cost for an inclusive date range from one complete published calculation. Omit \`group\_by\` for workspace totals and service costs; use \`group\_by=model\` to include each model's pricing status and applied rate records. The optional \`service\_id\` filter is applied before aggregation.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"CostResponse":{"anyOf":[{"$ref":"#/components/schemas/CostOverviewResponse"},{"$ref":"#/components/schemas/CostModelsResponse"}]},"CostOverviewResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace whose usage or cost is reported."},"period":{"$ref":"#/components/schemas/Period","description":"Inclusive requested date range."},"calculation_run_id":{"type":"string","format":"uuid","title":"Calculation Run Id","description":"Immutable published calculation run selected for the entire range."},"totals":{"$ref":"#/components/schemas/CostTotals"},"services":{"items":{"$ref":"#/components/schemas/ServiceCost"},"type":"array","title":"Services","description":"Services ordered by descending calculated cost."}},"type":"object","required":["workspace_id","period","calculation_run_id","totals","services"],"title":"CostOverviewResponse","description":"Cost overview returned when `group_by` is omitted."},"Period":{"properties":{"start_date":{"type":"string","format":"date","title":"Start Date"},"end_date":{"type":"string","format":"date","title":"End Date"}},"type":"object","required":["start_date","end_date"],"title":"Period","description":"Inclusive calendar-date range covered by the report."},"CostTotals":{"properties":{"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd","description":"Priced subtotal rounded to cents; excludes unpriced usage. Zero for no usage, null if none can be priced."},"cost_per_conversation_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cost Per Conversation Usd","description":"Priced linked cost divided by distinct priced linked conversations; cents, or null without a denominator."},"has_unpriced_usage":{"type":"boolean","title":"Has Unpriced Usage","description":"Whether any usage in the period could not be priced."},"unpriced_tokens":{"type":"integer","title":"Unpriced Tokens","description":"Tokens excluded from calculated cost because no rate applied."}},"type":"object","required":["calculated_cost_usd","cost_per_conversation_usd","has_unpriced_usage","unpriced_tokens"],"title":"CostTotals","description":"Workspace cost totals for the requested period."},"ServiceCost":{"properties":{"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id","description":"Service identifier, or null for cost that could not be attributed."},"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd","description":"This service's priced subtotal rounded to cents; excludes unpriced usage, null if none can be priced."},"cost_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Share","description":"Service priced subtotal / total priced cost in the selected scope, after any service filter.\nNull when the service has no priced cost or the denominator is zero or unavailable."}},"type":"object","required":["service_id","calculated_cost_usd","cost_share"],"title":"ServiceCost","description":"Cost attributed to one service."},"CostModelsResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace whose usage or cost is reported."},"period":{"$ref":"#/components/schemas/Period","description":"Inclusive requested date range."},"calculation_run_id":{"type":"string","format":"uuid","title":"Calculation Run Id","description":"Immutable published calculation run selected for the entire range."},"models":{"items":{"$ref":"#/components/schemas/ModelCost"},"type":"array","title":"Models"}},"type":"object","required":["workspace_id","period","calculation_run_id","models"],"title":"CostModelsResponse","description":"Cost grouped by model, returned for `group_by=model`."},"ModelCost":{"properties":{"model_id":{"type":"string","title":"Model Id"},"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd","description":"Model priced subtotal rounded to cents; can be partial when is_priced is false. Null if none is priced."},"cost_share":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Share","description":"Model priced subtotal / all model priced subtotals in the selected scope, after any service filter.\nIncludes partial subtotals; null when this model has no priced cost or the denominator is zero."},"is_priced":{"type":"boolean","title":"Is Priced","description":"Whether every contributing usage row for this model is priced; false can coexist with a priced subtotal."},"unpriced_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unpriced Reason","description":"One reason contributing usage could not be priced; null when all usage is priced."},"applied_rates":{"items":{"$ref":"#/components/schemas/AppliedRate"},"type":"array","title":"Applied Rates","description":"Effective-date and context-band rates used for this model."}},"type":"object","required":["model_id","calculated_cost_usd","cost_share","is_priced","unpriced_reason","applied_rates"],"title":"ModelCost","description":"Cost and pricing status for one model."},"AppliedRate":{"properties":{"input_rate_effective_from":{"type":"string","format":"date","title":"Input Rate Effective From","description":"Inclusive first usage date for the input rate."},"input_rate_effective_to":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Input Rate Effective To","description":"Exclusive end usage date for the input rate; null means no end date."},"output_rate_effective_from":{"type":"string","format":"date","title":"Output Rate Effective From","description":"Inclusive first usage date for the output rate."},"output_rate_effective_to":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Output Rate Effective To","description":"Exclusive end usage date for the output rate; null means no end date."},"cached_rate_effective_from":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Cached Rate Effective From","description":"Inclusive first usage date for the cached-input rate; null if no cached rate applied."},"cached_rate_effective_to":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Cached Rate Effective To","description":"Exclusive end usage date for the cached-input rate; null if unbounded or no cached rate applied."},"min_input_tokens":{"type":"integer","title":"Min Input Tokens","description":"Inclusive lower bound on per-request context input tokens for the input-rate band."},"max_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Input Tokens","description":"Inclusive upper bound on per-request context input tokens; null means unbounded."},"input_per_million":{"type":"string","title":"Input Per Million","description":"USD per million uncached input tokens, as a decimal string."},"cached_input_per_million":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cached Input Per Million","description":"USD per million cached input tokens; null if no cached rate applied."},"output_per_million":{"type":"string","title":"Output Per Million","description":"USD per million output tokens, as a decimal string."}},"type":"object","required":["input_rate_effective_from","input_rate_effective_to","output_rate_effective_from","output_rate_effective_to","cached_rate_effective_from","cached_rate_effective_to","min_input_tokens","max_input_tokens","input_per_million","cached_input_per_million","output_per_million"],"title":"AppliedRate","description":"Rate record applied to this model during the requested period."}}},"paths":{"/v1/{workspace_id}/cost":{"get":{"tags":["Billing"],"summary":"Get workspace LLM cost","description":"Return Amigo-admin-only LLM cost for an inclusive date range from one complete published calculation. Omit `group_by` for workspace totals and service costs; use `group_by=model` to include each model's pricing status and applied rate records. The optional `service_id` filter is applied before aggregation.","operationId":"get-workspace-cost","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"start_date","in":"query","required":true,"schema":{"type":"string","format":"date","description":"First usage date to include.","title":"Start Date"},"description":"First usage date to include."},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","format":"date","description":"Last usage date to include. It cannot be in the future.","title":"End Date"},"description":"Last usage date to include. It cannot be in the future."},{"name":"service_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Limit the report to usage attributed to this service.","title":"Service Id"},"description":"Limit the report to usage attributed to this service."},{"name":"group_by","in":"query","required":false,"schema":{"anyOf":[{"const":"model","type":"string"},{"type":"null"}],"description":"Return model costs and applied rates instead of the overview.","title":"Group By"},"description":"Return model costs and applied rates instead of the overview."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostResponse"}}}},"401":{"description":"Missing or invalid authentication credentials."},"403":{"description":"Caller cannot access this workspace or is not an Amigo administrator."},"404":{"description":"Workspace not found."},"410":{"description":"Workspace is archived."},"422":{"description":"Query validation failed: dates must be valid, `end_date` cannot be in the future, `start_date` must not follow `end_date`, and `group_by` must be supported."},"429":{"description":"Read rate limit exceeded."},"503":{"description":"The service or billing data is unavailable, or no complete calculation covers the period."}}}}}}
```

## Get workspace usage and cost overview

> Return customer-visible production-classified LLM usage and calculated model-provider cost for an inclusive UTC date range. The optional \`service\_id\` filter is applied before aggregation. Unsupported v0 provenance and attribution fields remain null and successful responses report \`data\_status=partial\`.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"UsageCostOverviewResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"period":{"$ref":"#/components/schemas/UsageCostPeriod"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id","description":"Service identifier; null for unattributed usage."},"attribution_status":{"type":"string","const":"best_effort","title":"Attribution Status"},"attribution":{"anyOf":[{"$ref":"#/components/schemas/UsageCostAttribution"},{"type":"null"}]},"data_status":{"type":"string","enum":["complete","partial","delayed","failed"],"title":"Data Status","description":"V0 returns partial for a published calculation, or failed when no complete calculation covers the period."},"data_as_of":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Data As Of","description":"Source-event freshness; null because the published facts do not retain it."},"calculation_run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculation Run Id","description":"Opaque published-calculation identifier; null when no complete calculation covers the period."},"rate_card_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rate Card Version","description":"Reproducible rate-card identifier; null because the published facts do not retain it."},"currency":{"type":"string","const":"USD","title":"Currency"},"totals":{"anyOf":[{"$ref":"#/components/schemas/UsageCostOverviewTotals"},{"type":"null"}]},"daily":{"anyOf":[{"items":{"$ref":"#/components/schemas/UsageCostDaily"},"type":"array"},{"type":"null"}],"title":"Daily","description":"Ascending UTC dates, zero-filled across the requested period; null when no complete calculation is available."},"services":{"anyOf":[{"items":{"$ref":"#/components/schemas/UsageCostService"},"type":"array"},{"type":"null"}],"title":"Services"},"latest_close":{"anyOf":[{"$ref":"#/components/schemas/UsageCostLatestClose"},{"type":"null"}],"description":"Null in V0 because no monthly close uses the same production-classification policy."}},"type":"object","required":["workspace_id","period","service_id","attribution_status","attribution","data_status","data_as_of","calculation_run_id","rate_card_version","currency","totals","daily","services","latest_close"],"title":"UsageCostOverviewResponse","description":"Customer usage and calculated model-provider cost overview."},"UsageCostPeriod":{"properties":{"start_date":{"type":"string","format":"date","title":"Start Date"},"end_date":{"type":"string","format":"date","title":"End Date"},"timezone":{"type":"string","const":"UTC","title":"Timezone"}},"type":"object","required":["start_date","end_date","timezone"],"title":"UsageCostPeriod","description":"Inclusive UTC calendar-date range covered by the report."},"UsageCostAttribution":{"properties":{"conversation_attribution_rate":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Conversation Attribution Rate","description":"Linked-token share; null because the published facts do not retain linked-token totals."},"service_attribution_rate":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Service Attribution Rate","description":"Service-attributed input and output tokens / all tokens in the selected scope; null with no tokens."},"may_include_amigo_operated_usage":{"type":"boolean","title":"May Include Amigo Operated Usage","description":"Whether production-classified totals may include usage operated by Amigo."}},"type":"object","required":["conversation_attribution_rate","service_attribution_rate","may_include_amigo_operated_usage"],"title":"UsageCostAttribution","description":"Known coverage and limitations of usage attribution."},"UsageCostOverviewTotals":{"properties":{"conversation_count":{"type":"integer","title":"Conversation Count","description":"Distinct linked conversations in the selected scope, not the sum of per-model counts."},"request_count":{"type":"integer","title":"Request Count","description":"Provider requests in the selected scope, including requests without a linked conversation."},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"},"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd","description":"Priced subtotal rounded to cents; excludes unpriced usage. Zero for no usage, null if none can be priced."},"cost_per_conversation_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cost Per Conversation Usd","description":"Priced linked cost / distinct priced linked conversations; cents, or null without a denominator."},"has_unpriced_usage":{"type":"boolean","title":"Has Unpriced Usage","description":"Whether any selected usage is omitted from the priced subtotal."},"unpriced_tokens":{"type":"integer","title":"Unpriced Tokens","description":"Input and output tokens belonging to usage that could not be priced."}},"type":"object","required":["conversation_count","request_count","uncached_input_tokens","cached_input_tokens","output_tokens","calculated_cost_usd","cost_per_conversation_usd","has_unpriced_usage","unpriced_tokens"],"title":"UsageCostOverviewTotals","description":"Production-classified usage and calculated cost totals."},"UsageCostDaily":{"properties":{"usage_date":{"type":"string","format":"date","title":"Usage Date"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"}},"type":"object","required":["usage_date","uncached_input_tokens"],"title":"UsageCostDaily","description":"Uncached input-token usage for one UTC date."},"UsageCostService":{"properties":{"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id","description":"Service identifier; null for unattributed usage."},"service_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service Name","description":"Service name at the latest metadata refresh; null if unavailable. Unattributed for a null service ID."},"conversation_count":{"type":"integer","title":"Conversation Count"},"request_count":{"type":"integer","title":"Request Count"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"},"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd","description":"Service priced subtotal rounded to cents; excludes unpriced usage, null if none can be priced."},"cost_per_conversation_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cost Per Conversation Usd","description":"Service priced linked cost / its distinct priced linked conversations; cents, or null without a denominator."},"cost_share":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Cost Share","description":"Service priced subtotal / workspace-wide priced subtotal, even when service_id filters the response.\nNull if this service has no priced cost or the workspace denominator is zero or unavailable."},"has_unpriced_usage":{"type":"boolean","title":"Has Unpriced Usage","description":"Whether any usage for this service is omitted from its priced subtotal."},"unpriced_tokens":{"type":"integer","title":"Unpriced Tokens"}},"type":"object","required":["service_id","service_name","conversation_count","request_count","uncached_input_tokens","cached_input_tokens","output_tokens","calculated_cost_usd","cost_per_conversation_usd","cost_share","has_unpriced_usage","unpriced_tokens"],"title":"UsageCostService","description":"Production-classified usage and calculated cost for one service."},"UsageCostLatestClose":{"properties":{"close_month":{"type":"string","format":"date","title":"Close Month"},"status":{"type":"string","const":"complete","title":"Status"},"calculated_at":{"type":"string","format":"date-time","title":"Calculated At"},"calculation_run_id":{"type":"string","title":"Calculation Run Id"},"rate_card_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rate Card Version"},"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd"},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cached Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"},"has_unpriced_usage":{"type":"boolean","title":"Has Unpriced Usage"},"unpriced_tokens":{"type":"integer","title":"Unpriced Tokens"}},"type":"object","required":["close_month","status","calculated_at","calculation_run_id","rate_card_version","calculated_cost_usd","uncached_input_tokens","cached_input_tokens","output_tokens","has_unpriced_usage","unpriced_tokens"],"title":"UsageCostLatestClose","description":"Latest compatible completed monthly close, when available."},"UsageCostErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/UsageCostError"}},"type":"object","required":["error"],"title":"UsageCostErrorResponse","description":"Stable error envelope for the customer usage-cost contract."},"UsageCostError":{"properties":{"code":{"type":"string","enum":["invalid_usage_period","workspace_usage_forbidden","workspace_not_found","usage_data_unavailable"],"title":"Code"},"message":{"type":"string","title":"Message"}},"type":"object","required":["code","message"],"title":"UsageCostError"}}},"paths":{"/v1/{workspace_id}/usage-cost/overview":{"get":{"tags":["Billing"],"summary":"Get workspace usage and cost overview","description":"Return customer-visible production-classified LLM usage and calculated model-provider cost for an inclusive UTC date range. The optional `service_id` filter is applied before aggregation. Unsupported v0 provenance and attribution fields remain null and successful responses report `data_status=partial`.","operationId":"get-workspace-usage-cost-overview","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"start_date","in":"query","required":true,"schema":{"type":"string","format":"date","description":"First usage date to include.","title":"Start Date"},"description":"First usage date to include."},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","format":"date","description":"Last usage date to include. It cannot be in the future.","title":"End Date"},"description":"Last usage date to include. It cannot be in the future."},{"name":"service_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Limit the report to usage attributed to this service.","title":"Service Id"},"description":"Limit the report to usage attributed to this service."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageCostOverviewResponse"}}}},"400":{"description":"Invalid usage period.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageCostErrorResponse"}}}},"401":{"description":"Missing or invalid authentication credentials."},"403":{"description":"Caller cannot view this workspace's usage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageCostErrorResponse"}}}},"404":{"description":"Workspace does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageCostErrorResponse"}}}},"410":{"description":"Workspace is archived."},"422":{"description":"Query validation failed because `service_id` is not a valid UUID."},"429":{"description":"Read rate limit exceeded."},"503":{"description":"Usage data is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageCostErrorResponse"}}}}}}}}}
```

## Get workspace usage and cost by model

> Return customer-visible production-classified LLM usage and calculated model-provider cost grouped by model. The optional \`service\_id\` filter is applied before aggregation. Rates and money are decimal strings.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"UsageCostModelsResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"period":{"$ref":"#/components/schemas/Period"},"service_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Service Id"},"conversation_count":{"type":"integer","title":"Conversation Count","description":"Distinct linked conversations in the selected scope; conversations shared by models are counted once."},"currency":{"type":"string","const":"USD","title":"Currency"},"models":{"items":{"$ref":"#/components/schemas/UsageCostModel"},"type":"array","title":"Models"}},"type":"object","required":["workspace_id","period","service_id","conversation_count","currency","models"],"title":"UsageCostModelsResponse","description":"Customer usage and calculated model-provider cost grouped by model."},"Period":{"properties":{"start_date":{"type":"string","format":"date","title":"Start Date"},"end_date":{"type":"string","format":"date","title":"End Date"}},"type":"object","required":["start_date","end_date"],"title":"Period","description":"Inclusive calendar-date range covered by the report."},"UsageCostModel":{"properties":{"model_id":{"type":"string","title":"Model Id"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider"},"request_count":{"type":"integer","title":"Request Count"},"calls_per_conversation":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Calls Per Conversation","description":"This model's linked provider requests / its distinct linked conversations; null if none are linked."},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"type":"integer","title":"Cached Input Tokens"},"cache_rate":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Cache Rate","description":"Cached input tokens / total input tokens; null when there are no input tokens."},"output_tokens":{"type":"integer","title":"Output Tokens"},"applied_rates":{"items":{"$ref":"#/components/schemas/UsageCostAppliedRate"},"type":"array","title":"Applied Rates"},"calculated_cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Calculated Cost Usd","description":"Model cost rounded to cents; null if any contributing usage is unpriced, including partially priced models."},"cost_share":{"anyOf":[{"type":"number","maximum":1,"minimum":0},{"type":"null"}],"title":"Cost Share","description":"Model cost / fully priced model costs in the selected scope, after any service filter.\nPartially priced models are excluded from both sides; null if unpriced or the denominator is zero."},"is_priced":{"type":"boolean","title":"Is Priced","description":"Whether every contributing usage row for this model is priced."},"unpriced_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unpriced Reason","description":"One reason contributing usage could not be priced; null when all usage is priced."}},"type":"object","required":["model_id","provider","request_count","calls_per_conversation","uncached_input_tokens","cached_input_tokens","cache_rate","output_tokens","applied_rates","calculated_cost_usd","cost_share","is_priced","unpriced_reason"],"title":"UsageCostModel","description":"Production-classified usage and calculated cost for one model."},"UsageCostAppliedRate":{"properties":{"rate_card_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rate Card Version","description":"Null in V0 because the published facts do not retain a reproducible rate-card identifier."},"effective_from":{"type":"string","format":"date-time","title":"Effective From","description":"Inclusive input-rate start date, represented as midnight UTC."},"effective_to":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Effective To","description":"Exclusive input-rate end date at midnight UTC; null means no end date."},"input_per_million":{"type":"string","title":"Input Per Million","description":"USD per million uncached input tokens, as a decimal string."},"cached_input_per_million":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cached Input Per Million","description":"USD per million cached input tokens; null if no cached rate applied."},"output_per_million":{"type":"string","title":"Output Per Million","description":"USD per million output tokens, as a decimal string."}},"type":"object","required":["rate_card_version","effective_from","effective_to","input_per_million","cached_input_per_million","output_per_million"],"title":"UsageCostAppliedRate","description":"Rate record applied to this model during the requested period."},"UsageCostErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/UsageCostError"}},"type":"object","required":["error"],"title":"UsageCostErrorResponse","description":"Stable error envelope for the customer usage-cost contract."},"UsageCostError":{"properties":{"code":{"type":"string","enum":["invalid_usage_period","workspace_usage_forbidden","workspace_not_found","usage_data_unavailable"],"title":"Code"},"message":{"type":"string","title":"Message"}},"type":"object","required":["code","message"],"title":"UsageCostError"}}},"paths":{"/v1/{workspace_id}/usage-cost/models":{"get":{"tags":["Billing"],"summary":"Get workspace usage and cost by model","description":"Return customer-visible production-classified LLM usage and calculated model-provider cost grouped by model. The optional `service_id` filter is applied before aggregation. Rates and money are decimal strings.","operationId":"get-workspace-usage-cost-models","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"start_date","in":"query","required":true,"schema":{"type":"string","format":"date","description":"First usage date to include.","title":"Start Date"},"description":"First usage date to include."},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","format":"date","description":"Last usage date to include. It cannot be in the future.","title":"End Date"},"description":"Last usage date to include. It cannot be in the future."},{"name":"service_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Limit the report to usage attributed to this service.","title":"Service Id"},"description":"Limit the report to usage attributed to this service."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageCostModelsResponse"}}}},"400":{"description":"Invalid usage period.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageCostErrorResponse"}}}},"401":{"description":"Missing or invalid authentication credentials."},"403":{"description":"Caller cannot view this workspace's usage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageCostErrorResponse"}}}},"404":{"description":"Workspace does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageCostErrorResponse"}}}},"410":{"description":"Workspace is archived."},"422":{"description":"Query validation failed because `service_id` is not a valid UUID."},"429":{"description":"Read rate limit exceeded."},"503":{"description":"Usage data is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageCostErrorResponse"}}}}}}}}}
```

## Get workspace usage excluded from production-classified totals

> Return simulation, playground, customer-test, Amigo-internal, and unresolved usage excluded from the customer's production-classified totals. The optional \`service\_id\` filter is applied before aggregation.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"UsageCostExcludedResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"period":{"$ref":"#/components/schemas/Period"},"classes":{"items":{"$ref":"#/components/schemas/UsageCostExcludedClass"},"type":"array","title":"Classes"}},"type":"object","required":["workspace_id","period","classes"],"title":"UsageCostExcludedResponse","description":"Usage explicitly excluded from production-classified totals."},"Period":{"properties":{"start_date":{"type":"string","format":"date","title":"Start Date"},"end_date":{"type":"string","format":"date","title":"End Date"}},"type":"object","required":["start_date","end_date"],"title":"Period","description":"Inclusive calendar-date range covered by the report."},"UsageCostExcludedClass":{"properties":{"usage_class":{"type":"string","enum":["simulation","playground_test","customer_test","amigo_internal","unknown"],"title":"Usage Class"},"exclusion_reason":{"type":"string","enum":["simulation","playground","customer_test","amigo_internal","operator_attribution_unavailable"],"title":"Exclusion Reason"},"conversation_count":{"type":"integer","title":"Conversation Count","description":"Distinct linked conversations in this excluded class; zero when none are linked."},"request_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Request Count","description":"Provider requests in this class; null when the source cannot supply a request count."},"uncached_input_tokens":{"type":"integer","title":"Uncached Input Tokens"},"cached_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cached Input Tokens","description":"Cached input tokens in this class; null when the source cannot supply the count."},"output_tokens":{"type":"integer","title":"Output Tokens"}},"type":"object","required":["usage_class","exclusion_reason","conversation_count","request_count","uncached_input_tokens","cached_input_tokens","output_tokens"],"title":"UsageCostExcludedClass","description":"Usage totals and exclusion reason for one non-production class."},"UsageCostErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/UsageCostError"}},"type":"object","required":["error"],"title":"UsageCostErrorResponse","description":"Stable error envelope for the customer usage-cost contract."},"UsageCostError":{"properties":{"code":{"type":"string","enum":["invalid_usage_period","workspace_usage_forbidden","workspace_not_found","usage_data_unavailable"],"title":"Code"},"message":{"type":"string","title":"Message"}},"type":"object","required":["code","message"],"title":"UsageCostError"}}},"paths":{"/v1/{workspace_id}/usage-cost/excluded":{"get":{"tags":["Billing"],"summary":"Get workspace usage excluded from production-classified totals","description":"Return simulation, playground, customer-test, Amigo-internal, and unresolved usage excluded from the customer's production-classified totals. The optional `service_id` filter is applied before aggregation.","operationId":"get-workspace-usage-cost-excluded","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"start_date","in":"query","required":true,"schema":{"type":"string","format":"date","description":"First usage date to include.","title":"Start Date"},"description":"First usage date to include."},{"name":"end_date","in":"query","required":true,"schema":{"type":"string","format":"date","description":"Last usage date to include. It cannot be in the future.","title":"End Date"},"description":"Last usage date to include. It cannot be in the future."},{"name":"service_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Limit the report to usage attributed to this service.","title":"Service Id"},"description":"Limit the report to usage attributed to this service."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageCostExcludedResponse"}}}},"400":{"description":"Invalid usage period.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageCostErrorResponse"}}}},"401":{"description":"Missing or invalid authentication credentials."},"403":{"description":"Caller cannot view this workspace's usage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageCostErrorResponse"}}}},"404":{"description":"Workspace does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageCostErrorResponse"}}}},"410":{"description":"Workspace is archived."},"422":{"description":"Query validation failed because `service_id` is not a valid UUID."},"429":{"description":"Read rate limit exceeded."},"503":{"description":"Usage data is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageCostErrorResponse"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.concurrence.com/api-reference/readme/platform/billing.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.