Sustema

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."
}

Related schemas

All API operations