BUILD WITH INFERMAX
Usage & Account
Read project consumption and recorded work units without confusing unknown measurements with zero.
Attribute work to a feature or run
Inference accepts an optional X-Infermax-Attribution header containing feature, runId and, for a sub-agent, parentRunId. Feature is declared by your client, not inferred from prompt content. Historical requests without attribution remain unknown.
{"feature":"AGENT","runId":"<opaque UUID>"}SUB_AGENT requires an existing parent run in the same project. Run lineage is immutable and each request is counted once in parent reports. Keep prompts, agent names, user data and credentials out of attribution.
/v1/usage/reportGET/v1/usage/chargesGET/v1/allocation-usagePOST/v1/telemetry/queryPOST/v1/telemetry/distributionsGET/v1/inference/usageGET/v1/compute/usageGET/v1/compute/usage/intervalsBounded project consumption; unknown attribution and tokens preserved. Not charges.
Authorization: Bearer · project scope
Parameters
| Name / location | Requirement | Definition |
|---|---|---|
fromquery | Required | {
"type": "string"
} |
toquery | Required | {
"type": "string"
} |
timezonequery | Required | {
"default": "UTC",
"allOf": [
{
"$ref": "#/components/schemas/Object"
}
]
} |
bucketquery | Required | {
"type": "string",
"enum": [
"day",
"week",
"month"
]
} |
groupByquery | Required | {
"type": "string",
"enum": [
"project",
"key",
"deployment",
"model",
"modality",
"feature",
"run"
]
} |
projectIdquery | Optional | {
"type": "string"
} |
keyIdquery | Optional | {
"type": "string"
} |
deploymentIdquery | Optional | Legacy deployment or serving revision ID; rows retain both identities separately. {
"type": "string"
} |
modelquery | Optional | {
"type": "string"
} |
modalityquery | Optional | {
"type": "string",
"enum": [
"TEXT",
"UNKNOWN"
]
} |
featurequery | Optional | {
"type": "string",
"enum": [
"DIRECT_API",
"AGENT",
"SUB_AGENT",
"TASK",
"UNKNOWN"
]
} |
executionModequery | Optional | {
"type": "string",
"enum": [
"SIMULATED",
"REAL",
"UNKNOWN"
]
} |
rootRunIdquery | Optional | Include a project-scoped run and all descendants, counting each request once. {
"type": "string"
} |
Responses
200 Successful operation.
application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"scope",
"authorizedProjectIds",
"from",
"to",
"timezone",
"bucket",
"groupBy",
"rootRunId",
"semantics",
"items"
],
"properties": {
"scope": {
"type": "string",
"enum": [
"PROJECT",
"AUTHORIZED_WORKSPACE_PROJECTS"
]
},
"authorizedProjectIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"from": {
"type": "string",
"format": "date-time"
},
"to": {
"type": "string",
"format": "date-time"
},
"timezone": {
"type": "string"
},
"bucket": {
"type": "string",
"enum": [
"day",
"week",
"month"
]
},
"groupBy": {
"type": "string",
"enum": [
"project",
"key",
"deployment",
"model",
"modality",
"feature",
"run"
]
},
"rootRunId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"semantics": {
"type": "object",
"additionalProperties": false,
"required": [
"time",
"window",
"weekStart",
"units",
"money",
"lineage",
"empty",
"attribution"
],
"properties": {
"time": {
"type": "string"
},
"window": {
"type": "string"
},
"weekStart": {
"type": "string"
},
"units": {
"type": "string"
},
"money": {
"type": "string"
},
"lineage": {
"type": "string"
},
"empty": {
"type": "string"
},
"attribution": {
"type": "string"
}
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"bucket_start",
"execution_mode",
"requests",
"succeeded",
"unsuccessful",
"pending_or_unknown",
"measured_records",
"unknown_records",
"unrecorded_requests",
"known_input_tokens",
"known_output_tokens",
"input_tokens",
"output_tokens"
],
"properties": {
"bucket_start": {
"type": "string",
"format": "date-time"
},
"execution_mode": {
"type": "string",
"enum": [
"SIMULATED",
"REAL",
"UNKNOWN",
"CONFLICT"
]
},
"requests": {
"type": "string",
"pattern": "^[0-9]+$"
},
"succeeded": {
"type": "string",
"pattern": "^[0-9]+$"
},
"unsuccessful": {
"type": "string",
"pattern": "^[0-9]+$"
},
"pending_or_unknown": {
"type": "string",
"pattern": "^[0-9]+$"
},
"measured_records": {
"type": "string",
"pattern": "^[0-9]+$"
},
"unknown_records": {
"type": "string",
"pattern": "^[0-9]+$"
},
"unrecorded_requests": {
"type": "string",
"pattern": "^[0-9]+$"
},
"known_input_tokens": {
"type": "string",
"pattern": "^[0-9]+$",
"nullable": true
},
"known_output_tokens": {
"type": "string",
"pattern": "^[0-9]+$",
"nullable": true
},
"input_tokens": {
"type": "string",
"pattern": "^[0-9]+$",
"nullable": true
},
"output_tokens": {
"type": "string",
"pattern": "^[0-9]+$",
"nullable": true
},
"project_id": {
"type": "string",
"format": "uuid"
},
"api_key_id": {
"type": "string",
"format": "uuid"
},
"deployment_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"revision_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"endpoint_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"model_id": {
"type": "string"
},
"modality": {
"type": "string"
},
"feature": {
"type": "string"
},
"feature_source": {
"type": "string",
"nullable": true
},
"run_id": {
"type": "string",
"format": "uuid",
"nullable": true
},
"parent_run_id": {
"type": "string",
"format": "uuid",
"nullable": true
}
}
}
}
}
}400 Fail-closed request or dependency error.
application/json
{
"$ref": "#/components/schemas/ProductManagementErrorEnvelope"
}401 Fail-closed request or dependency error.
application/json
{
"$ref": "#/components/schemas/ProductManagementErrorEnvelope"
}403 Fail-closed request or dependency error.
application/json
{
"$ref": "#/components/schemas/ProductManagementErrorEnvelope"
}404 Fail-closed request or dependency error.
application/json
{
"$ref": "#/components/schemas/ProductManagementErrorEnvelope"
}409 Fail-closed request or dependency error.
application/json
{
"$ref": "#/components/schemas/ProductManagementErrorEnvelope"
}413 Fail-closed request or dependency error.
application/json
{
"$ref": "#/components/schemas/ProductManagementErrorEnvelope"
}422 Fail-closed request or dependency error.
application/json
{
"$ref": "#/components/schemas/ProductManagementErrorEnvelope"
}429 Fail-closed request or dependency error.
application/json
{
"$ref": "#/components/schemas/ProductManagementErrorEnvelope"
}500 Fail-closed request or dependency error.
application/json
{
"$ref": "#/components/schemas/ProductManagementErrorEnvelope"
}503 Fail-closed request or dependency error.
application/json
{
"$ref": "#/components/schemas/ProductManagementErrorEnvelope"
}Own-project posted customer tariffs; missing postings are not zero or complete billing
Authorization: Bearer · project scope
Parameters
| Name / location | Requirement | Definition |
|---|---|---|
fromquery | Required | {
"format": "date-time",
"type": "string"
} |
toquery | Required | {
"format": "date-time",
"type": "string"
} |
Responses
200
application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"domain",
"scope",
"from",
"to",
"currency",
"status",
"netAmountMicros",
"entries",
"charges",
"reversals",
"items",
"truncated",
"receiptCoverage",
"semantics"
],
"properties": {
"domain": {
"type": "string",
"enum": [
"CUSTOMER_CHARGE",
"SUPPLIER_SETTLEMENT"
]
},
"scope": {
"type": "string",
"enum": [
"PROJECT",
"PROVIDER"
]
},
"from": {
"type": "string",
"format": "date-time"
},
"to": {
"type": "string",
"format": "date-time"
},
"currency": {
"type": "string",
"enum": [
"USD"
]
},
"status": {
"type": "string",
"enum": [
"TARIFF_UNAVAILABLE",
"NO_POSTED_ENTRIES",
"POSTED"
]
},
"netAmountMicros": {
"type": "string",
"pattern": "^-?[0-9]+$",
"nullable": true
},
"entries": {
"type": "string",
"pattern": "^[0-9]+$"
},
"charges": {
"type": "string",
"pattern": "^[0-9]+$"
},
"reversals": {
"type": "string",
"pattern": "^[0-9]+$"
},
"truncated": {
"type": "boolean"
},
"semantics": {
"type": "string"
},
"receiptCoverage": {
"type": "object",
"additionalProperties": false,
"required": [
"real_requests",
"known_receipts",
"unknown_or_incomplete_receipts",
"unposted_known_receipts",
"posted_receipts",
"reversed_receipts",
"dispatched_unrecorded_requests",
"not_dispatched_unrecorded_requests",
"status",
"timeBasis"
],
"properties": {
"real_requests": {
"type": "string",
"pattern": "^[0-9]+$"
},
"known_receipts": {
"type": "string",
"pattern": "^[0-9]+$"
},
"unknown_or_incomplete_receipts": {
"type": "string",
"pattern": "^[0-9]+$"
},
"unposted_known_receipts": {
"type": "string",
"pattern": "^[0-9]+$"
},
"posted_receipts": {
"type": "string",
"pattern": "^[0-9]+$"
},
"reversed_receipts": {
"type": "string",
"pattern": "^[0-9]+$"
},
"dispatched_unrecorded_requests": {
"type": "string",
"pattern": "^[0-9]+$"
},
"not_dispatched_unrecorded_requests": {
"type": "string",
"pattern": "^[0-9]+$"
},
"status": {
"type": "string",
"enum": [
"NO_REAL_REQUESTS",
"COMPLETE",
"PARTIAL"
]
},
"timeBasis": {
"type": "string"
}
}
},
"items": {
"type": "array",
"maxItems": 100,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"kind",
"amountMicros",
"currency",
"occurredAt",
"postedAt",
"tariffId",
"tariffVersion",
"digest",
"reversesId"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"CHARGE",
"REVERSAL"
]
},
"amountMicros": {
"type": "string",
"pattern": "^-?[0-9]+$"
},
"currency": {
"type": "string",
"enum": [
"USD"
]
},
"occurredAt": {
"type": "string",
"format": "date-time"
},
"postedAt": {
"type": "string",
"format": "date-time"
},
"tariffId": {
"type": "string"
},
"tariffVersion": {
"type": "string"
},
"digest": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"reversesId": {
"type": "string",
"format": "uuid",
"nullable": true
}
}
}
}
}
}400 Invalid request
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}401 Missing or revoked API key
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}403 Role or policy denied
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}404 Resource absent or not visible
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}409 Idempotency, capacity, quota or state conflict
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}413 Request body exceeds 64 KiB
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}422 Invalid reference
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}429 Rate limit; honor Retry-After
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}503 Dependency unavailable
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}Read allocation occupancy
Authorization: Bearer · project scope
Parameters
| Name / location | Requirement | Definition |
|---|---|---|
limitquery | Optional | {
"maximum": 100,
"default": 50,
"type": "number"
} |
afterquery | Optional | {
"type": "string"
} |
Responses
200 Successful operation.
application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"items",
"nextCursor",
"quantityKind",
"billingStatus"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"binding_id",
"instance_id",
"project_id",
"provider_id",
"execution_mode",
"started_at",
"ended_at",
"gpu_seconds",
"certainty",
"state",
"source_event_id"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"binding_id": {
"type": "string",
"format": "uuid"
},
"instance_id": {
"type": "string",
"format": "uuid"
},
"project_id": {
"type": "string",
"format": "uuid"
},
"provider_id": {
"type": "string",
"format": "uuid"
},
"execution_mode": {
"type": "string",
"enum": [
"REAL",
"SIMULATED"
]
},
"started_at": {
"type": "string",
"format": "date-time"
},
"ended_at": {
"type": "string",
"format": "date-time"
},
"gpu_seconds": {
"type": "string",
"nullable": true
},
"certainty": {
"type": "string",
"enum": [
"KNOWN",
"UNKNOWN"
]
},
"state": {
"type": "string"
},
"source_event_id": {
"type": "string"
}
}
}
},
"nextCursor": {
"type": "string",
"format": "uuid",
"nullable": true
},
"quantityKind": {
"type": "string",
"enum": [
"ALLOCATION_OCCUPANCY"
]
},
"billingStatus": {
"type": "string",
"enum": [
"NOT_BILLING"
]
}
}
}400 Fail-closed request or dependency error.
application/json
{
"$ref": "#/components/schemas/ProductManagementErrorEnvelope"
}401 Fail-closed request or dependency error.
application/json
{
"$ref": "#/components/schemas/ProductManagementErrorEnvelope"
}403 Fail-closed request or dependency error.
application/json
{
"$ref": "#/components/schemas/ProductManagementErrorEnvelope"
}404 Fail-closed request or dependency error.
application/json
{
"$ref": "#/components/schemas/ProductManagementErrorEnvelope"
}409 Fail-closed request or dependency error.
application/json
{
"$ref": "#/components/schemas/ProductManagementErrorEnvelope"
}413 Fail-closed request or dependency error.
application/json
{
"$ref": "#/components/schemas/ProductManagementErrorEnvelope"
}422 Fail-closed request or dependency error.
application/json
{
"$ref": "#/components/schemas/ProductManagementErrorEnvelope"
}429 Fail-closed request or dependency error.
application/json
{
"$ref": "#/components/schemas/ProductManagementErrorEnvelope"
}500 Fail-closed request or dependency error.
application/json
{
"$ref": "#/components/schemas/ProductManagementErrorEnvelope"
}503 Fail-closed request or dependency error.
application/json
{
"$ref": "#/components/schemas/ProductManagementErrorEnvelope"
}Bounded project ledger telemetry; missing observations remain unavailable
Authorization: Bearer · project scope
Parameters
No additional parameters are declared.
Request body · required
application/json
{
"type": "object",
"additionalProperties": false,
"required": [
"projectId",
"deploymentId",
"from",
"to",
"stepSeconds",
"metrics"
],
"properties": {
"projectId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"deploymentId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"from": {
"type": "string",
"format": "date-time"
},
"to": {
"type": "string",
"format": "date-time"
},
"stepSeconds": {
"type": "integer",
"minimum": 1,
"maximum": 86400
},
"metrics": {
"type": "array",
"minItems": 1,
"maxItems": 12,
"uniqueItems": true,
"items": {
"type": "string"
}
}
}
}Responses
200
No response body schema is declared for this status.
201 Successful operation.
application/json
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": true
}400 Invalid request
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}401 Missing or revoked API key
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}403 Role or policy denied
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}404 Resource absent or not visible
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}409 Idempotency, capacity, quota or state conflict
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}413 Request body exceeds 64 KiB
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}422 Invalid reference
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}429 Rate limit; honor Retry-After
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}503 Dependency unavailable
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}Query latency distributions
Authorization: Bearer · project scope
Parameters
No additional parameters are declared.
Responses
200
application/json
{
"type": "object",
"additionalProperties": false,
"properties": {
"projectId": {
"type": "string",
"format": "uuid"
},
"from": {
"type": "string",
"format": "date-time"
},
"to": {
"type": "string",
"format": "date-time"
},
"unit": {
"type": "string",
"enum": [
"ms"
]
},
"quantiles": {
"type": "array",
"minItems": 3,
"maxItems": 3,
"items": {
"type": "number",
"enum": [
0.5,
0.95,
0.99
]
}
},
"source": {
"type": "string",
"enum": [
"inference_timing_samples",
"ClickHouse projection of inference_timing_samples"
]
},
"aggregation": {
"type": "string"
},
"rows": {
"type": "array",
"maxItems": 12,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"execution_mode": {
"type": "string",
"enum": [
"REAL",
"SIMULATED",
null
],
"nullable": true
},
"outcome": {
"type": "string",
"enum": [
"SUCCEEDED",
"FAILED",
"CANCELLED",
"UNKNOWN"
]
},
"samples": {
"type": "integer",
"minimum": 0
},
"ttft_samples": {
"type": "integer",
"minimum": 0
},
"ttft_ms": {
"type": "array",
"nullable": true,
"minItems": 3,
"maxItems": 3,
"items": {
"type": "number",
"minimum": 0
}
},
"completion_ms": {
"type": "array",
"nullable": true,
"minItems": 3,
"maxItems": 3,
"items": {
"type": "number",
"minimum": 0
}
}
},
"required": [
"execution_mode",
"outcome",
"samples",
"ttft_samples",
"ttft_ms",
"completion_ms"
]
}
},
"status": {
"type": "string",
"enum": [
"MEASURED",
"UNAVAILABLE"
]
}
},
"required": [
"projectId",
"from",
"to",
"unit",
"quantiles",
"source",
"aggregation",
"rows",
"status"
]
}400 Invalid request
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}401 Missing or revoked API key
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}403 Role or policy denied
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}404 Resource absent or not visible
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}409 Idempotency, capacity, quota or state conflict
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}413 Request body exceeds 64 KiB
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}422 Invalid reference
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}429 Rate limit; honor Retry-After
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}503 Dependency unavailable
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}Inference work units with execution mode and measurement status
Authorization: Bearer · project scope
Parameters
| Name / location | Requirement | Definition |
|---|---|---|
limitquery | Optional | {
"maximum": 100,
"default": 50,
"type": "number"
} |
afterquery | Optional | {
"type": "string"
} |
Responses
200 Persisted contract response; runtime readiness is not implied
application/json
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"project_id": {
"type": "string",
"format": "uuid"
},
"request_id": {
"type": "string",
"format": "uuid"
},
"source_event_id": {
"type": "string"
},
"execution_mode": {
"type": "string",
"enum": [
"SIMULATED",
"REAL"
]
},
"input_tokens": {
"type": "string",
"nullable": true,
"description": "PostgreSQL bigint serialized as a decimal string"
},
"output_tokens": {
"type": "string",
"nullable": true
},
"measurement_status": {
"type": "string",
"enum": [
"MEASURED",
"UNKNOWN"
]
},
"reconciliation": {
"type": "object",
"properties": {
"outcome": {
"type": "string"
},
"measurement_status": {
"type": "string"
},
"input_tokens": {
"type": "string",
"nullable": true
},
"output_tokens": {
"type": "string",
"nullable": true
}
},
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"nextCursor": {
"type": "string",
"format": "uuid",
"nullable": true
}
}
}400 Invalid request
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}401 Missing or revoked API key
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}403 Role or policy denied
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}404 Resource absent or not visible
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}409 Idempotency, capacity, quota or state conflict
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}413 Request body exceeds 64 KiB
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}422 Invalid reference
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}429 Rate limit; honor Retry-After
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}503 Dependency unavailable
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}Finalized sandbox occupancy after release; not an invoice or live GPU measurement
Authorization: Bearer · project scope · management access required
Parameters
| Name / location | Requirement | Definition |
|---|---|---|
limitquery | Optional | {
"maximum": 100,
"default": 50,
"type": "number"
} |
afterquery | Optional | {
"type": "string"
} |
Responses
200 Successful operation.
application/json
{
"type": "object",
"required": [
"items",
"nextCursor"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"project_id": {
"type": "string",
"format": "uuid"
},
"instance_id": {
"type": "string",
"format": "uuid"
},
"source_event_id": {
"type": "string"
},
"started_at": {
"type": "string",
"format": "date-time"
},
"ended_at": {
"type": "string",
"format": "date-time"
},
"gpu_seconds": {
"type": "string"
},
"unit_seconds": {
"type": "string"
},
"execution_mode": {
"type": "string",
"enum": [
"SIMULATED"
]
}
}
}
},
"nextCursor": {
"type": "string",
"format": "uuid",
"nullable": true
}
}
}400 Invalid request
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}401 Missing or revoked API key
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}403 Role or policy denied
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}404 Resource absent or not visible
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}409 Idempotency, capacity, quota or state conflict
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}413 Request body exceeds 64 KiB
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}422 Invalid reference
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}429 Rate limit; honor Retry-After
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}503 Dependency unavailable
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}Incremental simulated occupancy intervals, unknown rates; do not add to final lifetime totals
Authorization: Bearer · project scope · management access required
Parameters
| Name / location | Requirement | Definition |
|---|---|---|
limitquery | Optional | {
"maximum": 100,
"default": 50,
"type": "number"
} |
afterquery | Optional | {
"type": "string"
} |
Responses
200 Successful operation.
application/json
{
"type": "object",
"required": [
"items",
"nextCursor"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"project_id": {
"type": "string",
"format": "uuid"
},
"instance_id": {
"type": "string",
"format": "uuid"
},
"source_event_id": {
"type": "string"
},
"started_at": {
"type": "string",
"format": "date-time"
},
"ended_at": {
"type": "string",
"format": "date-time"
},
"gpu_seconds": {
"type": "string"
},
"unit_seconds": {
"type": "string"
},
"execution_mode": {
"type": "string",
"enum": [
"SIMULATED"
]
},
"resource_id": {
"type": "string",
"format": "uuid"
},
"rate_status": {
"type": "string",
"enum": [
"UNKNOWN"
]
},
"quantity_kind": {
"type": "string",
"enum": [
"OCCUPANCY"
]
},
"final_interval": {
"type": "boolean"
}
}
}
},
"nextCursor": {
"type": "string",
"format": "uuid",
"nullable": true
}
}
}400 Invalid request
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}401 Missing or revoked API key
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}403 Role or policy denied
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}404 Resource absent or not visible
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}409 Idempotency, capacity, quota or state conflict
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}413 Request body exceeds 64 KiB
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}422 Invalid reference
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}429 Rate limit; honor Retry-After
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}503 Dependency unavailable
application/json
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}Schema definitions
Expand a named definition to resolve #/components/schemas/… references in this contract. These definitions contain only schemas reachable from the published Customer operations.
ProductCatalogPage
{
"type": "object",
"additionalProperties": false,
"required": [
"items",
"nextCursor"
],
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProductCatalogItem"
},
"maxItems": 100
},
"nextCursor": {
"type": "string",
"nullable": true
}
}
}ProductCatalogItem
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"displayName",
"family",
"modalities",
"capabilities",
"limits",
"visibility",
"entitled",
"availability",
"qualification",
"metadataSource",
"price"
],
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"displayName": {
"type": "string"
},
"family": {
"type": "string",
"nullable": true
},
"modalities": {
"type": "array",
"items": {
"type": "string",
"enum": [
"text",
"image",
"audio",
"video"
]
},
"nullable": true
},
"capabilities": {
"$ref": "#/components/schemas/ProductCatalogCapabilities"
},
"limits": {
"$ref": "#/components/schemas/ProductCatalogLimits"
},
"visibility": {
"type": "string",
"enum": [
"PUBLISHED"
]
},
"entitled": {
"type": "boolean"
},
"availability": {
"$ref": "#/components/schemas/ProductCatalogAvailability"
},
"qualification": {
"$ref": "#/components/schemas/ProductCatalogQualification"
},
"metadataSource": {
"type": "string",
"nullable": true
},
"price": {
"type": "object",
"additionalProperties": false,
"required": [
"amount",
"currency",
"unit",
"source",
"version",
"approvedAt"
],
"properties": {
"amount": {
"type": "string",
"pattern": "^[0-9]{1,18}([.][0-9]{1,12})?$"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"unit": {
"type": "string",
"enum": [
"MILLION_INPUT_TOKENS",
"MILLION_OUTPUT_TOKENS",
"REQUEST"
]
},
"source": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"version": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"approvedAt": {
"type": "string",
"format": "date-time"
}
},
"nullable": true
}
}
}ProductCatalogCapabilities
{
"type": "object",
"additionalProperties": false,
"required": [
"tools",
"streaming",
"structuredOutput"
],
"properties": {
"tools": {
"type": "boolean",
"nullable": true
},
"streaming": {
"type": "boolean",
"nullable": true
},
"structuredOutput": {
"type": "boolean",
"nullable": true
}
}
}ProductCatalogLimits
{
"type": "object",
"additionalProperties": false,
"required": [
"contextTokens",
"maxOutputTokens"
],
"properties": {
"contextTokens": {
"type": "integer",
"minimum": 1
},
"maxOutputTokens": {
"type": "integer",
"minimum": 1
}
}
}ProductCatalogAvailability
{
"type": "object",
"additionalProperties": false,
"required": [
"status",
"reason",
"executionMode"
],
"properties": {
"status": {
"type": "string",
"enum": [
"AVAILABLE",
"UNAVAILABLE"
]
},
"reason": {
"type": "string",
"enum": [
"NOT_ENTITLED",
"REVISION_PROOF_CURRENT",
"NO_FRESH_READY_REVISION"
]
},
"executionMode": {
"type": "string",
"enum": [
"SIMULATED",
"REAL",
null
],
"nullable": true
}
}
}ProductCatalogQualification
{
"type": "object",
"additionalProperties": false,
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"REAL_PROOF_CURRENT",
"FIXTURE_PROOF_CURRENT",
"UNVERIFIED"
]
}
}
}ProductManagementErrorEnvelope
{
"oneOf": [
{
"$ref": "#/components/schemas/ProductManagementFilterError"
},
{
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code"
],
"properties": {
"code": {
"enum": [
"RATE_LIMITED"
],
"type": "string"
}
}
}
}
}
]
}ProductManagementFilterError
{
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message",
"type",
"requestId",
"retryable",
"dispatched"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"server_error",
"rate_limit_error",
"invalid_request_error"
]
},
"requestId": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"dispatched": {
"enum": [
false
],
"type": "boolean"
},
"details": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}ProductCatalogDetail
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"displayName",
"family",
"modalities",
"capabilities",
"limits",
"visibility",
"entitled",
"availability",
"qualification",
"metadataSource",
"price",
"apiExample",
"configurationGuidance"
],
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"displayName": {
"type": "string"
},
"family": {
"type": "string",
"nullable": true
},
"modalities": {
"type": "array",
"items": {
"type": "string",
"enum": [
"text",
"image",
"audio",
"video"
]
},
"nullable": true
},
"capabilities": {
"$ref": "#/components/schemas/ProductCatalogCapabilities"
},
"limits": {
"$ref": "#/components/schemas/ProductCatalogLimits"
},
"visibility": {
"type": "string",
"enum": [
"PUBLISHED"
]
},
"entitled": {
"type": "boolean"
},
"availability": {
"$ref": "#/components/schemas/ProductCatalogAvailability"
},
"qualification": {
"$ref": "#/components/schemas/ProductCatalogQualification"
},
"metadataSource": {
"type": "string",
"nullable": true
},
"price": {
"type": "object",
"additionalProperties": false,
"required": [
"amount",
"currency",
"unit",
"source",
"version",
"approvedAt"
],
"properties": {
"amount": {
"type": "string",
"pattern": "^[0-9]{1,18}([.][0-9]{1,12})?$"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"unit": {
"type": "string",
"enum": [
"MILLION_INPUT_TOKENS",
"MILLION_OUTPUT_TOKENS",
"REQUEST"
]
},
"source": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"version": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"approvedAt": {
"type": "string",
"format": "date-time"
}
},
"nullable": true
},
"apiExample": {
"type": "object",
"additionalProperties": false,
"required": [
"method",
"path",
"body"
],
"properties": {
"method": {
"type": "string",
"enum": [
"POST"
]
},
"path": {
"type": "string",
"enum": [
"/v1/chat/completions"
]
},
"body": {
"type": "object",
"additionalProperties": false,
"required": [
"model",
"messages",
"stream",
"max_tokens"
],
"properties": {
"model": {
"type": "string"
},
"messages": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"role",
"content"
],
"properties": {
"role": {
"type": "string",
"enum": [
"user"
]
},
"content": {
"type": "string"
}
}
},
"minItems": 1,
"maxItems": 1
},
"stream": {
"enum": [
false
],
"type": "boolean"
},
"max_tokens": {
"type": "integer",
"minimum": 1,
"maximum": 128
}
}
}
},
"nullable": true
},
"configurationGuidance": {
"type": "array",
"items": {
"type": "string"
}
}
}
}ManagedQuoteInput
{
"type": "object",
"properties": {
"offerId": {
"type": "string"
},
"requestedEndAt": {
"type": "string"
}
},
"required": [
"offerId",
"requestedEndAt"
]
}WaitlistInput
{
"type": "object",
"properties": {
"intentId": {
"type": "string"
},
"email": {
"type": "boolean"
}
},
"required": [
"intentId",
"email"
]
}ReservationInput
{
"type": "object",
"properties": {
"acceptedQuoteId": {
"type": "string",
"description": "Exact immutable liability quote accepted for a budget-controlled allocation."
},
"acceptedPolicyId": {
"type": "string",
"description": "Exact approved compute policy accepted by customer; required for policy-backed supply."
},
"offerId": {
"type": "string"
},
"units": {
"type": "number",
"example": 1,
"description": "Whole allocation units, not fractional GPUs."
},
"requestedEndAt": {
"type": "string",
"example": "2026-11-01T12:00:00Z",
"description": "UTC end time, within 31 days. Expiry triggers operator review, not automatic destruction."
}
},
"required": [
"offerId",
"units",
"requestedEndAt"
]
}InstanceInput
{
"type": "object",
"properties": {
"reservationId": {
"type": "string"
}
},
"required": [
"reservationId"
]
}Object
{
"type": "object",
"properties": {}
}