ENTITY developer reference
UsageResult
Candidate documentation for reading and synthetic examples. Account creation, live API access, SDKs, collections and MCP are not available here. A released service profile and matching integration instructions are required before use.
This is a documentation reading view of an unreleased candidate, not a downloadable replacement schema. Public wire names, types and constraints are retained except for the explicitly marked private-only subsets and route patterns. Private governance references are explained in public language. Use only a separately released, verified generation for clients. Read the explicit exclusions.
PackagePolicy: its retained title says it is not current UsageResult, while UsageResult requires package_policy. Follow the explicit required property and its referenced structure; the stale title does not make the field optional.
This is the public candidate schema reading view. Read it with the operation that uses it; a representable field does not establish enabled coverage or entitlement.
Owned accounting-period summary, not a new allowance. The period binding preserves original base/sponsored policy; current limits and spendability remain current projections. accepted_offer_id agrees with period_binding.offer_id. No private funding or other-tenant information is inferred from this aggregate. For getUsage with period_id omitted, resolve the actual current owned accounting period. While free renewal is pending and no current sponsored period has been published, return the existing dependency_unavailable503 with null operation/status references and no new debit; do not present a prior period as current or fabricate a new period. A caller may explicitly request its original prior period under existing usage.read/ownership checks: retain historical settled/reserved/available accounting amounts, but closed-period headroom.eligible_available_units and spendable_at_snapshot are zero and no prior units become reusable. The signed-in console’s free-tier status remains the existing explicit last_closed/renewal_pending status path. Reading either surface never creates funds or renewal.
Declared type: "object"
Declared fields
This list shows only properties declared directly in this schema. Required labels refer only to this schema’s own required array. Referenced, composed and conditional rules can add constraints; a field not listed as required here is not guaranteed to be optional.
organisation_id
Listed in this schema’s required array.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for organisation_id
{
"anyOf": [
{
"type": "string",
"format": "uuid",
"x-profile-maxLength": "string_characters_max"
},
{
"type": "null"
}
]
}environment
Listed in this schema’s required array.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for environment
{
"$ref": "#/components/schemas/Environment"
}period_id
Listed in this schema’s required array.
- Declared type
"string"- Declared format
"uuid"
Reading definition for period_id
{
"type": "string",
"format": "uuid",
"x-profile-maxLength": "string_characters_max"
}period_start
Listed in this schema’s required array.
- Declared type
"string"- Declared format
"date-time"
Reading definition for period_start
{
"type": "string",
"format": "date-time",
"x-profile-maxLength": "string_characters_max"
}period_end
Listed in this schema’s required array.
- Declared type
"string"- Declared format
"date-time"
Reading definition for period_end
{
"type": "string",
"format": "date-time",
"x-profile-maxLength": "string_characters_max"
}accepted_offer_id
Listed in this schema’s required array.
- Declared type
"string"
Reading definition for accepted_offer_id
{
"type": "string",
"x-profile-maxLength": "string_characters_max"
}unit
Listed in this schema’s required array.
- Declared type
"string"
Reading definition for unit
{
"type": "string",
"x-profile-maxLength": "string_characters_max"
}unit_scale
Listed in this schema’s required array.
- Declared type
"integer"
Reading definition for unit_scale
{
"type": "integer",
"minimum": 1
}granted
Listed in this schema’s required array.
Initial included grant plus unique funded upgrade grants for this period. Never the full target monthly allowance unless this is its funded full renewal.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for granted
{
"$ref": "#/components/schemas/Units",
"description": "Initial included grant plus unique funded upgrade grants for this period. Never the full target monthly allowance unless this is its funded full renewal."
}reserved
Listed in this schema’s required array.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for reserved
{
"$ref": "#/components/schemas/Units"
}settled
Listed in this schema’s required array.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for settled
{
"$ref": "#/components/schemas/Units"
}adjustments_signed
Listed in this schema’s required array.
- Declared type
"string"
Reading definition for adjustments_signed
{
"type": "string",
"pattern": "^(0|-?[1-9][0-9]*)$",
"x-profile-maxLength": "string_characters_max",
"maxLength": 31
}available
Listed in this schema’s required array.
Available included subscription/free period units, including funded prorated upgrades; top-up lots remain separate.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for available
{
"$ref": "#/components/schemas/Units",
"description": "Available included subscription/free period units, including funded prorated upgrades; top-up lots remain separate."
}as_of
Listed in this schema’s required array.
- Declared type
"string"- Declared format
"date-time"
Reading definition for as_of
{
"type": "string",
"format": "date-time",
"x-profile-maxLength": "string_characters_max"
}reporting_lag_seconds
Listed in this schema’s required array.
- Declared type
"integer"
Reading definition for reporting_lag_seconds
{
"type": "integer",
"minimum": 0
}rate_limit_per_second
Listed in this schema’s required array.
- Declared type
"integer"
Reading definition for rate_limit_per_second
{
"type": "integer",
"minimum": 1
}concurrency_limit
Listed in this schema’s required array.
- Declared type
"integer"
Reading definition for concurrency_limit
{
"type": "integer",
"minimum": 1
}budget_ceiling
Listed in this schema’s required array.
Total ceiling of the unique workspace/period row in headroom.limits, not its remaining headroom and not the grant amount.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for budget_ceiling
{
"$ref": "#/components/schemas/Units",
"description": "Total ceiling of the unique workspace/period row in headroom.limits, not its remaining headroom and not the grant amount."
}spendable_at_snapshot
Listed in this schema’s required array.
min(headroom.eligible_available_units, each headroom.limits[].remaining_units). A customer headroom snapshot; rights, rate/concurrency/capacity and duration-eligible funds are rechecked atomically at admission.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for spendable_at_snapshot
{
"$ref": "#/components/schemas/Units",
"description": "min(headroom.eligible_available_units, each headroom.limits[].remaining_units). A customer headroom snapshot; rights, rate/concurrency/capacity and duration-eligible funds are rechecked atomically at admission."
}package_policy
Listed in this schema’s required array.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for package_policy
{
"$ref": "#/components/schemas/PackagePolicy"
}access_tier
Listed in this schema’s required array.
- Declared type
"string"
Reading definition for access_tier
{
"type": "string",
"enum": [
"free_testing",
"paid_standard",
"custom"
],
"x-profile-maxLength": "string_characters_max"
}workspace_id
Listed in this schema’s required array.
- Declared type
"string"- Declared format
"uuid"
Reading definition for workspace_id
{
"type": "string",
"format": "uuid",
"x-profile-maxLength": "string_characters_max"
}workspace_kind
Listed in this schema’s required array.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for workspace_kind
{
"enum": [
"personal",
"company"
]
}credit_balances
Listed in this schema’s required array.
Same unit/scale and current eligible scope as request. Personal/free scope has zero top-up counters and not_applicable replenishment. No billing amounts or purchasing authority.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for credit_balances
{
"$ref": "#/components/schemas/CreditBalances",
"description": "Same unit/scale and current eligible scope as request. Personal/free scope has zero top-up counters and not_applicable replenishment. No billing amounts or purchasing authority."
}subscription
Listed in this schema’s required array.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for subscription
{
"anyOf": [
{
"$ref": "#/components/schemas/SubscriptionUsage"
},
{
"type": "null"
}
]
}classification
Listed in this schema’s required array.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for classification
{
"anyOf": [
{
"$ref": "#/components/schemas/ICUsage"
},
{
"type": "null"
}
]
}headroom
Listed in this schema’s required array.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for headroom
{
"$ref": "#/components/schemas/UsageHeadroom"
}period_binding
Listed in this schema’s required array.
Original base/sponsored period policy only: funded_period_id equals period_id. This is not attribution of all underlying top-up, upgrade or remedy funding to one offer. Adjustments and late settlements remain on their original admission periods; detailed finance/receipt allocations retain every origin.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for period_binding
{
"$ref": "#/components/schemas/OfferBinding",
"description": "Original base/sponsored period policy only: funded_period_id equals period_id. This is not attribution of all underlying top-up, upgrade or remedy funding to one offer. Adjustments and late settlements remain on their original admission periods; detailed finance/receipt allocations retain every origin."
}Schema reading view
Read all retained constraints, including any allOf, oneOf, anyOf, conditional and additional-property constraints. The field list does not combine branches. Explicitly marked private-only omissions mean this view is not an executable substitute for the original schema or a released contract.
{
"type": "object",
"properties": {
"organisation_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"x-profile-maxLength": "string_characters_max"
},
{
"type": "null"
}
]
},
"environment": {
"$ref": "#/components/schemas/Environment"
},
"period_id": {
"type": "string",
"format": "uuid",
"x-profile-maxLength": "string_characters_max"
},
"period_start": {
"type": "string",
"format": "date-time",
"x-profile-maxLength": "string_characters_max"
},
"period_end": {
"type": "string",
"format": "date-time",
"x-profile-maxLength": "string_characters_max"
},
"accepted_offer_id": {
"type": "string",
"x-profile-maxLength": "string_characters_max"
},
"unit": {
"type": "string",
"x-profile-maxLength": "string_characters_max"
},
"unit_scale": {
"type": "integer",
"minimum": 1
},
"granted": {
"$ref": "#/components/schemas/Units",
"description": "Initial included grant plus unique funded upgrade grants for this period. Never the full target monthly allowance unless this is its funded full renewal."
},
"reserved": {
"$ref": "#/components/schemas/Units"
},
"settled": {
"$ref": "#/components/schemas/Units"
},
"adjustments_signed": {
"type": "string",
"pattern": "^(0|-?[1-9][0-9]*)$",
"x-profile-maxLength": "string_characters_max",
"maxLength": 31
},
"available": {
"$ref": "#/components/schemas/Units",
"description": "Available included subscription/free period units, including funded prorated upgrades; top-up lots remain separate."
},
"as_of": {
"type": "string",
"format": "date-time",
"x-profile-maxLength": "string_characters_max"
},
"reporting_lag_seconds": {
"type": "integer",
"minimum": 0
},
"rate_limit_per_second": {
"type": "integer",
"minimum": 1
},
"concurrency_limit": {
"type": "integer",
"minimum": 1
},
"budget_ceiling": {
"$ref": "#/components/schemas/Units",
"description": "Total ceiling of the unique workspace/period row in headroom.limits, not its remaining headroom and not the grant amount."
},
"spendable_at_snapshot": {
"$ref": "#/components/schemas/Units",
"description": "min(headroom.eligible_available_units, each headroom.limits[].remaining_units). A customer headroom snapshot; rights, rate/concurrency/capacity and duration-eligible funds are rechecked atomically at admission."
},
"package_policy": {
"$ref": "#/components/schemas/PackagePolicy"
},
"access_tier": {
"type": "string",
"enum": [
"free_testing",
"paid_standard",
"custom"
],
"x-profile-maxLength": "string_characters_max"
},
"workspace_id": {
"type": "string",
"format": "uuid",
"x-profile-maxLength": "string_characters_max"
},
"workspace_kind": {
"enum": [
"personal",
"company"
]
},
"credit_balances": {
"$ref": "#/components/schemas/CreditBalances",
"description": "Same unit/scale and current eligible scope as request. Personal/free scope has zero top-up counters and not_applicable replenishment. No billing amounts or purchasing authority."
},
"subscription": {
"anyOf": [
{
"$ref": "#/components/schemas/SubscriptionUsage"
},
{
"type": "null"
}
]
},
"classification": {
"anyOf": [
{
"$ref": "#/components/schemas/ICUsage"
},
{
"type": "null"
}
]
},
"headroom": {
"$ref": "#/components/schemas/UsageHeadroom"
},
"period_binding": {
"$ref": "#/components/schemas/OfferBinding",
"description": "Original base/sponsored period policy only: funded_period_id equals period_id. This is not attribution of all underlying top-up, upgrade or remedy funding to one offer. Adjustments and late settlements remain on their original admission periods; detailed finance/receipt allocations retain every origin."
}
},
"required": [
"organisation_id",
"environment",
"period_id",
"period_start",
"period_end",
"accepted_offer_id",
"unit",
"unit_scale",
"granted",
"reserved",
"settled",
"adjustments_signed",
"available",
"as_of",
"reporting_lag_seconds",
"rate_limit_per_second",
"concurrency_limit",
"budget_ceiling",
"spendable_at_snapshot",
"package_policy",
"access_tier",
"workspace_id",
"workspace_kind",
"credit_balances",
"subscription",
"classification",
"headroom",
"period_binding"
],
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"workspace_kind": {
"const": "personal"
}
}
},
"then": {
"properties": {
"organisation_id": {
"type": "null"
},
"environment": {
"const": "evaluation"
},
"access_tier": {
"const": "free_testing"
}
}
}
},
{
"if": {
"properties": {
"workspace_kind": {
"const": "company"
}
}
},
"then": {
"properties": {
"organisation_id": {
"type": "string",
"format": "uuid",
"x-profile-maxLength": "string_characters_max"
}
}
}
},
{
"if": {
"properties": {
"access_tier": {
"const": "free_testing"
}
}
},
"then": {
"properties": {
"credit_balances": {
"properties": {
"top_up_available_units": {
"const": "0"
},
"top_up_reserved_units": {
"const": "0"
},
"top_up_held_units": {
"const": "0"
},
"next_top_up_expiry_at": {
"type": "null"
},
"replenishment_status": {
"const": "not_applicable"
}
}
}
}
}
},
{
"if": {
"properties": {
"access_tier": {
"const": "free_testing"
}
}
},
"then": {
"properties": {
"subscription": {
"type": "null"
}
}
}
},
{
"if": {
"properties": {
"access_tier": {
"const": "paid_standard"
}
}
},
"then": {
"properties": {
"subscription": {
"$ref": "#/components/schemas/SubscriptionUsage"
}
}
}
},
{
"if": {
"properties": {
"access_tier": {
"const": "free_testing"
}
},
"required": [
"access_tier"
]
},
"then": {
"properties": {
"environment": {
"const": "evaluation"
},
"period_binding": {
"properties": {
"agreement_id": {
"type": "null"
},
"agreement_revision": {
"type": "null"
},
"funded_period_id": {
"type": "string",
"format": "uuid"
}
}
}
}
}
}
],
"description": "Owned accounting-period summary, not a new allowance. The period binding preserves original base/sponsored policy; current limits and spendability remain current projections. accepted_offer_id agrees with period_binding.offer_id. No private funding or other-tenant information is inferred from this aggregate. For getUsage with period_id omitted, resolve the actual current owned accounting period. While free renewal is pending and no current sponsored period has been published, return the existing dependency_unavailable503 with null operation/status references and no new debit; do not present a prior period as current or fabricate a new period. A caller may explicitly request its original prior period under existing usage.read/ownership checks: retain historical settled/reserved/available accounting amounts, but closed-period headroom.eligible_available_units and spendable_at_snapshot are zero and no prior units become reusable. The signed-in console’s free-tier status remains the existing explicit last_closed/renewal_pending status path. Reading either surface never creates funds or renewal."
}