Cost to Serve
Read workspace LLM usage and calculated cost, distinguish customer and staff access, and handle partial pricing, rollout limits, and retired cost routes.
Use the current usage and calculated LLM cost reports to inspect a workspace over a selected date range. These figures depend on recorded usage, attribution, and pricing coverage. They are not a customer invoice, a contracted price, or the total cost of operating the workspace.
Choose a Report
All reports require access to the workspace in the request path. Additional access rules differ:
Usage
Workspace credential with Data.view
Inspect production-classified usage or request model/class breakdowns
Customer usage and cost
Signed-in identity user with Data.view, plus workspace enablement
Compare production-classified usage and calculated model cost; inspect excluded usage separately
LLM inference cost
Concurrence administrator identity
Inspect staff-only LLM cost and applied rates
The customer usage-and-cost capability is disabled by default and must be enabled for the workspace. An API key cannot replace its signed-in user credential. A public schema entry is not proof that this workspace has access. See Authentication and API Keys.
Query Parameters
Use inclusive start_date and end_date values in YYYY-MM-DD form. The end cannot be in the future, and the start cannot follow the end. These reports do not require a closed month. An optional service_id narrows usage before aggregation.
Each report selects one complete published calculation covering every requested date. A valid date range can still have no available calculation; acceptance of an interaction does not establish that it has reached the report. The customer overview labels its dates as UTC.
Customer 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.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
First usage date to include.
Last usage date to include. It cannot be in the future.
Limit the report to usage attributed to this service.
Return model or usage-class breakdowns instead of the overview.
Successful Response
Missing or invalid authentication credentials.
Caller cannot access this workspace or lacks Data.view permission.
Workspace not found.
Workspace is archived.
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.
Read rate limit exceeded.
The service or billing data is unavailable, or no complete calculation covers the period.
GET /v1/{workspace_id}/usage?start_date=2026-01-01&end_date=2026-01-01 HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"period": {
"start_date": "2026-01-01",
"end_date": "2026-01-01"
},
"calculation_run_id": "123e4567-e89b-12d3-a456-426614174000",
"attribution": {
"conversation_attribution_rate": 1,
"service_attribution_rate": 1
},
"totals": {
"conversation_count": 1,
"request_count": 1,
"uncached_input_tokens": 1,
"cached_input_tokens": 1,
"output_tokens": 1,
"has_unpriced_usage": true,
"unpriced_tokens": 1
},
"daily": [
{
"usage_date": "2026-01-01",
"uncached_input_tokens": 1,
"cached_input_tokens": 1,
"output_tokens": 1
}
],
"services": [
{
"service_id": "123e4567-e89b-12d3-a456-426614174000",
"conversation_count": 1,
"request_count": 1,
"uncached_input_tokens": 1,
"cached_input_tokens": 1,
"output_tokens": 1
}
]
}Omit group_by for production totals, daily usage, attribution, and service breakdowns. Use group_by=model for model usage or group_by=class to inspect usage classes, including non-production usage. A request is a model-provider request; it is not a phone call or a distinct conversation. Conversation counts include linked conversations only.
Example Request
Use the regional API base and credential assigned to your workspace. Choose dates with published usage data; this read does not create resources or require cleanup.
Record the returned workspace, period, and calculation_run_id with your report. An unavailable calculation is not a zero-usage result.
Customer 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.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
First usage date to include.
Last usage date to include. It cannot be in the future.
Limit the report to usage attributed to this service.
Successful Response
Customer usage and calculated model-provider cost overview.
Service identifier; null for unattributed usage.
V0 returns partial for a published calculation, or failed when no complete calculation covers the period.
Source-event freshness; null because the published facts do not retain it.
Opaque published-calculation identifier; null when no complete calculation covers the period.
Reproducible rate-card identifier; null because the published facts do not retain it.
Invalid usage period.
Missing or invalid authentication credentials.
Caller cannot view this workspace's usage.
Workspace does not exist.
Workspace is archived.
Query validation failed because service_id is not a valid UUID.
Read rate limit exceeded.
Usage data is unavailable.
GET /v1/{workspace_id}/usage-cost/overview?start_date=2026-01-01&end_date=2026-01-01 HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"period": {
"start_date": "2026-01-01",
"end_date": "2026-01-01",
"timezone": "text"
},
"service_id": "123e4567-e89b-12d3-a456-426614174000",
"attribution_status": "text",
"attribution": {
"conversation_attribution_rate": 1,
"service_attribution_rate": 1,
"may_include_amigo_operated_usage": true
},
"data_status": "complete",
"data_as_of": "2026-01-01T00:00:00.000Z",
"calculation_run_id": "text",
"rate_card_version": "text",
"currency": "text",
"totals": {
"conversation_count": 1,
"request_count": 1,
"uncached_input_tokens": 1,
"cached_input_tokens": 1,
"output_tokens": 1,
"calculated_cost_usd": "text",
"cost_per_conversation_usd": "text",
"has_unpriced_usage": true,
"unpriced_tokens": 1
},
"daily": [
{
"usage_date": "2026-01-01",
"uncached_input_tokens": 1
}
],
"services": [
{
"service_id": "123e4567-e89b-12d3-a456-426614174000",
"service_name": "text",
"conversation_count": 1,
"request_count": 1,
"uncached_input_tokens": 1,
"cached_input_tokens": 1,
"output_tokens": 1,
"calculated_cost_usd": "text",
"cost_per_conversation_usd": "text",
"cost_share": 1,
"has_unpriced_usage": true,
"unpriced_tokens": 1
}
],
"latest_close": {
"close_month": "2026-01-01",
"status": "text",
"calculated_at": "2026-01-01T00:00:00.000Z",
"calculation_run_id": "text",
"rate_card_version": "text",
"calculated_cost_usd": "text",
"uncached_input_tokens": 1,
"cached_input_tokens": 1,
"output_tokens": 1,
"has_unpriced_usage": true,
"unpriced_tokens": 1
}
}The overview reports production-classified totals, daily uncached-input usage, and service breakdowns. In the current version, a published calculation returns data_status: "partial" and attribution_status: "best_effort". This is expected even when every requested date is covered: source freshness, reproducible rate-card version, conversation-attributed token share, and a compatible monthly close are not available. Their fields remain null. Production-classified totals may include Concurrence-operated usage.
Response Body
Inspect data_status before rendering totals. If no complete calculation covers the range, the overview returns HTTP 200 with data_status: "failed" and null totals, daily data, services, and calculation identifier. Show unavailable data rather than converting those nulls to zero. The models and excluded reports instead return 503 when no complete calculation is available.
Customer cost amounts and rates use decimal strings. The overview's calculated cost is a priced subtotal: it excludes unpriced usage and exposes has_unpriced_usage and unpriced_tokens. No usage yields "0.00"; usage that cannot be priced at all yields null. Review pricing coverage before comparing periods or services.
Models
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.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
First usage date to include.
Last usage date to include. It cannot be in the future.
Limit the report to usage attributed to this service.
Successful Response
Customer usage and calculated model-provider cost grouped by model.
Distinct linked conversations in the selected scope; conversations shared by models are counted once.
Invalid usage period.
Missing or invalid authentication credentials.
Caller cannot view this workspace's usage.
Workspace does not exist.
Workspace is archived.
Query validation failed because service_id is not a valid UUID.
Read rate limit exceeded.
Usage data is unavailable.
GET /v1/{workspace_id}/usage-cost/models?start_date=2026-01-01&end_date=2026-01-01 HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"period": {
"start_date": "2026-01-01",
"end_date": "2026-01-01"
},
"service_id": "123e4567-e89b-12d3-a456-426614174000",
"conversation_count": 1,
"currency": "text",
"models": [
{
"model_id": "text",
"provider": "text",
"request_count": 1,
"calls_per_conversation": 1,
"uncached_input_tokens": 1,
"cached_input_tokens": 1,
"cache_rate": 1,
"output_tokens": 1,
"applied_rates": [
{
"rate_card_version": "text",
"effective_from": "2026-01-01T00:00:00.000Z",
"effective_to": "2026-01-01T00:00:00.000Z",
"input_per_million": "text",
"cached_input_per_million": "text",
"output_per_million": "text"
}
],
"calculated_cost_usd": "text",
"cost_share": 1,
"is_priced": true,
"unpriced_reason": "text"
}
]
}Model Object
If any contributing usage for a model is unpriced, its customer model cost is null, including when some of its usage is priced. Consequently, summing visible model costs need not equal the overview's priced subtotal. Model cost shares use fully priced models in the selected scope. Overview service cost shares use the workspace-wide priced subtotal, even when service_id filters the response.
Excluded Usage
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.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
First usage date to include.
Last usage date to include. It cannot be in the future.
Limit the report to usage attributed to this service.
Successful Response
Usage explicitly excluded from production-classified totals.
Invalid usage period.
Missing or invalid authentication credentials.
Caller cannot view this workspace's usage.
Workspace does not exist.
Workspace is archived.
Query validation failed because service_id is not a valid UUID.
Read rate limit exceeded.
Usage data is unavailable.
GET /v1/{workspace_id}/usage-cost/excluded?start_date=2026-01-01&end_date=2026-01-01 HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"period": {
"start_date": "2026-01-01",
"end_date": "2026-01-01"
},
"classes": [
{
"usage_class": "simulation",
"exclusion_reason": "simulation",
"conversation_count": 1,
"request_count": 1,
"uncached_input_tokens": 1,
"cached_input_tokens": 1,
"output_tokens": 1
}
]
}Inspect simulation, playground, customer-test, Concurrence-internal, and unresolved usage separately from production-classified totals. Exclusion reflects the recorded classification; it does not prove that every production-classified request was customer-operated.
LLM Inference 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.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
First usage date to include.
Last usage date to include. It cannot be in the future.
Limit the report to usage attributed to this service.
Return model costs and applied rates instead of the overview.
Successful Response
Missing or invalid authentication credentials.
Caller cannot access this workspace or is not an Amigo administrator.
Workspace not found.
Workspace is archived.
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.
Read rate limit exceeded.
The service or billing data is unavailable, or no complete calculation covers the period.
GET /v1/{workspace_id}/cost?start_date=2026-01-01&end_date=2026-01-01 HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"period": {
"start_date": "2026-01-01",
"end_date": "2026-01-01"
},
"calculation_run_id": "123e4567-e89b-12d3-a456-426614174000",
"totals": {
"calculated_cost_usd": "text",
"cost_per_conversation_usd": "text",
"has_unpriced_usage": true,
"unpriced_tokens": 1
},
"services": [
{
"service_id": "123e4567-e89b-12d3-a456-426614174000",
"calculated_cost_usd": "text",
"cost_share": 1
}
]
}This is the staff-only report. A workspace administrator role alone does not grant access; a Concurrence administrator identity is required. Omit group_by for production workspace and service costs, or use group_by=model for model pricing status and applied rate records. Unlike the retired interface, it uses the selected date range rather than close_month.
Infrastructure Cost
The former infrastructure endpoint is removed. The current LLM reports do not supply pooled compute/storage allocations, reconcile the full operating bill, or promise a completed monthly close. Coordinate any infrastructure cost review separately with Concurrence.
Response Codes
The embedded contracts define each report's errors. For customer usage-and-cost reads, a disabled workspace capability returns 503; an ineligible caller returns 403. Invalid dates return 400 on /usage-cost/* and 422 on /usage and /cost. The overview's HTTP 200 with data_status: "failed" must also be handled as unavailable data.
On an unavailable result, check workspace enablement and whether a calculation covers the entire period. Retry temporary failures with backoff, and retain the workspace, period, optional service filter, and error code for support. Do not retry an authorization failure with a different credential type unless that credential has the required access.
Notes
These reports are separate from metered customer billing and invoices. Use the applicable billing records and commercial agreement for amounts owed; see Cost and Latency Optimization for deployment planning.
Last updated
Was this helpful?