Sustema

ENTITY developer reference

Inspect usage and limits

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.

GET /v1/usage

Operation identifier: getUsage

This pure owned read creates no new business effect or debit. Its failure reports only not_started/unchanged with null operation/status references. Existing underlying financial uncertainty is shown in the successful owned status envelope; unavailable read dependencies use the existing dependency_unavailable retry path. Never report a new reservation/settlement or invent a polling operation for this read. 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.

Entity-Service-Profile carries the accepted profile_id; the endpoint pins its separate immutable revision. The retained template parameter description says “revision”; follow this current interpretation when reading that historical wording. No reserved example URL in the definitions is a live service destination.

Authentication

Apply the operation’s security requirement when present, otherwise the contract default below. These definitions do not provision access or qualify an authentication flow.

[
  {
    "bearerAuth": []
  }
]
Security scheme definitions
{
  "bearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "description": "Validated OAuth access token, never an ID token. Issuer/audience/token endpoint and scope mapping are deployment-profile values. ENTITY current role, data and budget policy additionally applies."
  }
}

Request parameters

Headers, path and query parameters from the candidate contract. Operation-specific definitions take precedence over inherited definitions with the same name and location. Request body fields appear in the reading view below.

period_id

query · Optional

Accepted own-workspace period; actual current period if omitted. During pending free renewal without a current funded period, omission returns dependency_unavailable503; an explicit owned historical period remains readable with zero current spendability.

Reading definition for period_id
{
  "name": "period_id",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "uuid",
    "maxLength": 36
  },
  "required": false,
  "description": "Accepted own-workspace period; actual current period if omitted. During pending free renewal without a current funded period, omission returns dependency_unavailable503; an explicit owned historical period remains readable with zero current spendability."
}

Request and response contract

The candidate operation is shown below with the declared documentation-only public-meaning projection. References open the corresponding public schema. No server URL or credential is supplied by this page.

{
  "operationId": "getUsage",
  "summary": "Inspect usage and limits",
  "parameters": [
    {
      "name": "period_id",
      "in": "query",
      "schema": {
        "type": "string",
        "format": "uuid",
        "maxLength": 36
      },
      "required": false,
      "description": "Accepted own-workspace period; actual current period if omitted. During pending free renewal without a current funded period, omission returns dependency_unavailable503; an explicit owned historical period remains readable with zero current spendability."
    }
  ],
  "responses": {
    "200": {
      "description": "Successful governed response; examples are synthetic and no endpoint is deployed by this specification.",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UsageResponse"
          },
          "example": {
            "data": {
              "organisation_id": "00000009-1111-4111-8111-000000000009",
              "environment": "synthetic-review",
              "period_id": "00000008-1111-4111-8111-000000000008",
              "period_start": "2026-09-01T00:00:00Z",
              "period_end": "2026-10-01T00:00:00Z",
              "accepted_offer_id": "11111111-1111-4111-8111-111111111111",
              "unit": "synthetic_operation_unit",
              "unit_scale": 1,
              "granted": "3000",
              "reserved": "0",
              "settled": "900",
              "adjustments_signed": "0",
              "available": "2100",
              "budget_ceiling": "5000",
              "spendable_at_snapshot": "2100",
              "as_of": "2026-09-07T10:00:00Z",
              "reporting_lag_seconds": 0,
              "rate_limit_per_second": 5,
              "concurrency_limit": 5,
              "package_policy": {
                "policy_id": "synthetic-policy-not-an-offer",
                "revision": 1,
                "effective_from": "2026-09-01T00:00:00Z",
                "effective_until": "2026-10-01T00:00:00Z",
                "aggregation": "workspace_environment",
                "period_boundary_resets_rate": false,
                "work": {
                  "bucket": {
                    "algorithm": "token_bucket",
                    "requests_per_second": 5,
                    "burst_requests": 10
                  },
                  "concurrent_work_max": 5
                },
                "recovery": {
                  "bucket": {
                    "algorithm": "token_bucket",
                    "requests_per_second": 2,
                    "burst_requests": 4
                  },
                  "requires_work_allowance": false
                }
              },
              "access_tier": "paid_standard",
              "workspace_id": "00000009-1111-4111-8111-000000000009",
              "workspace_kind": "company",
              "credit_balances": {
                "subscription_available_units": "2100",
                "top_up_available_units": "0",
                "top_up_reserved_units": "0",
                "top_up_held_units": "0",
                "total_available_units": "2100",
                "next_top_up_expiry_at": null,
                "replenishment_status": "disabled",
                "recovery_path": null,
                "service_adjustment_available_units": "0",
                "service_adjustment_reserved_units": "0",
                "service_adjustment_held_units": "0",
                "service_adjustment_pending_units": "0",
                "next_service_adjustment_expiry_at": null
              },
              "subscription": {
                "current_offer_id": "00000000-0000-4000-8000-000000000087",
                "current_offer_version": 2,
                "tariff_version": "illustrative-tariff-1",
                "full_monthly_included_units": "5000",
                "period_initial_granted_units": "1000",
                "period_upgrade_granted_units": "2000",
                "pending_change_status": "none",
                "next_offer_id": null,
                "next_offer_version": null,
                "next_monthly_included_units": null,
                "next_effective_at": null,
                "recovery_path": "/account"
              },
              "classification": null,
              "headroom": {
                "method_revision": "usage-headroom-0.1",
                "eligible_available_units": "2100",
                "limits": [
                  {
                    "scope": "workspace",
                    "window_kind": "period",
                    "window_id": "synthetic-period-1",
                    "window_start": "2026-09-01T00:00:00Z",
                    "window_end": "2026-10-01T00:00:00Z",
                    "ceiling_units": "5000",
                    "settled_units": "900",
                    "reserved_units": "0",
                    "remaining_units": "4100"
                  }
                ],
                "service_admission": "available",
                "meaning": "snapshot_not_reservation_or_duration_eligibility"
              },
              "period_binding": {
                "offer_id": "11111111-1111-4111-8111-111111111111",
                "offer_version": 1,
                "offer_sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
                "policy_pins": {
                  "tariff": {
                    "id": "synthetic-policy",
                    "version": "1",
                    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                  },
                  "terms": {
                    "id": "synthetic-policy",
                    "version": "1",
                    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                  },
                  "credit": {
                    "id": "synthetic-policy",
                    "version": "1",
                    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                  },
                  "refresh": {
                    "id": "synthetic-policy",
                    "version": "1",
                    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                  },
                  "retrieval": {
                    "id": "synthetic-policy",
                    "version": "1",
                    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                  },
                  "eligibility": {
                    "id": "synthetic-policy",
                    "version": "1",
                    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                  },
                  "protection": {
                    "id": "synthetic-policy",
                    "version": "1",
                    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                  },
                  "rights": {
                    "id": "synthetic-policy",
                    "version": "1",
                    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                  },
                  "success": {
                    "id": "synthetic-policy",
                    "version": "1",
                    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                  }
                },
                "agreement_id": "22222222-2222-4222-8222-222222222222",
                "agreement_revision": 1,
                "funded_period_id": "00000008-1111-4111-8111-000000000008",
                "selection_evidence_id": "22222222-2222-4222-8222-222222222222"
              }
            },
            "meta": {
              "request_id": "00000007-1111-4111-8111-000000000007",
              "served_at": "2026-09-07T10:00:00Z",
              "profile_revision": "synthetic-review-1",
              "synthetic": true,
              "replayed": false,
              "warnings": [
                "Illustration only; limits, retention and units are not approved production terms."
              ]
            }
          }
        }
      }
    },
    "400": {
      "description": "invalid_request",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Problem"
                  },
                  {
                    "properties": {
                      "code": {
                        "enum": [
                          "invalid_request"
                        ]
                      },
                      "status": {
                        "const": 400
                      }
                    }
                  }
                ]
              },
              {
                "properties": {
                  "usage_state": {
                    "enum": [
                      "not_started",
                      "unchanged"
                    ]
                  },
                  "operation_id": {
                    "type": "null"
                  },
                  "status_path": {
                    "type": "null"
                  },
                  "code": {
                    "not": {
                      "enum": [
                        "operation_in_progress",
                        "operation_reconciling",
                        "completion_uncertain",
                        "budget_exhausted",
                        "funding_window_too_short"
                      ]
                    }
                  }
                }
              }
            ]
          },
          "example": {
            "type": "urn:sustema:entity:problem:invalid_request",
            "title": "Malformed JSON, duplicate keys, timestamp, header or structural input.",
            "status": 400,
            "code": "invalid_request",
            "request_id": "00000007-1111-4111-8111-000000000007",
            "operation_id": null,
            "retry_action": "do_not_retry",
            "usage_state": "not_started"
          }
        }
      },
      "x-error-codes": [
        "invalid_request"
      ]
    },
    "401": {
      "description": "unauthenticated",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Problem"
                  },
                  {
                    "properties": {
                      "code": {
                        "enum": [
                          "unauthenticated"
                        ]
                      },
                      "status": {
                        "const": 401
                      }
                    }
                  }
                ]
              },
              {
                "properties": {
                  "usage_state": {
                    "enum": [
                      "not_started",
                      "unchanged"
                    ]
                  },
                  "operation_id": {
                    "type": "null"
                  },
                  "status_path": {
                    "type": "null"
                  },
                  "code": {
                    "not": {
                      "enum": [
                        "operation_in_progress",
                        "operation_reconciling",
                        "completion_uncertain",
                        "budget_exhausted",
                        "funding_window_too_short"
                      ]
                    }
                  }
                }
              }
            ]
          },
          "example": {
            "type": "urn:sustema:entity:problem:unauthenticated",
            "title": "Missing/invalid access token; no protected resource details.",
            "status": 401,
            "code": "unauthenticated",
            "request_id": "00000007-1111-4111-8111-000000000007",
            "operation_id": null,
            "retry_action": "reauthenticate",
            "usage_state": "not_started"
          }
        }
      },
      "x-error-codes": [
        "unauthenticated"
      ]
    },
    "403": {
      "description": "permission_denied; authority_revoked",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Problem"
                  },
                  {
                    "properties": {
                      "code": {
                        "enum": [
                          "permission_denied",
                          "authority_revoked"
                        ]
                      },
                      "status": {
                        "const": 403
                      }
                    }
                  }
                ]
              },
              {
                "properties": {
                  "usage_state": {
                    "enum": [
                      "not_started",
                      "unchanged"
                    ]
                  },
                  "operation_id": {
                    "type": "null"
                  },
                  "status_path": {
                    "type": "null"
                  },
                  "code": {
                    "not": {
                      "enum": [
                        "operation_in_progress",
                        "operation_reconciling",
                        "completion_uncertain",
                        "budget_exhausted",
                        "funding_window_too_short"
                      ]
                    }
                  }
                }
              }
            ]
          },
          "example": {
            "type": "urn:sustema:entity:problem:permission_denied",
            "title": "Authenticated principal lacks the action/resource grant.",
            "status": 403,
            "code": "permission_denied",
            "request_id": "00000007-1111-4111-8111-000000000007",
            "operation_id": null,
            "retry_action": "do_not_retry",
            "usage_state": "not_started"
          }
        }
      },
      "x-error-codes": [
        "permission_denied",
        "authority_revoked"
      ]
    },
    "404": {
      "description": "resource_not_found",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Problem"
                  },
                  {
                    "properties": {
                      "code": {
                        "enum": [
                          "resource_not_found"
                        ]
                      },
                      "status": {
                        "const": 404
                      }
                    }
                  }
                ]
              },
              {
                "properties": {
                  "usage_state": {
                    "enum": [
                      "not_started",
                      "unchanged"
                    ]
                  },
                  "operation_id": {
                    "type": "null"
                  },
                  "status_path": {
                    "type": "null"
                  },
                  "code": {
                    "not": {
                      "enum": [
                        "operation_in_progress",
                        "operation_reconciling",
                        "completion_uncertain",
                        "budget_exhausted",
                        "funding_window_too_short"
                      ]
                    }
                  }
                }
              }
            ]
          },
          "example": {
            "type": "urn:sustema:entity:problem:resource_not_found",
            "title": "Unknown resource, or tenant-private reference intentionally concealed.",
            "status": 404,
            "code": "resource_not_found",
            "request_id": "00000007-1111-4111-8111-000000000007",
            "operation_id": null,
            "retry_action": "do_not_retry",
            "usage_state": "not_started"
          }
        }
      },
      "x-error-codes": [
        "resource_not_found"
      ]
    },
    "422": {
      "description": "Bounded zero-unit refusal: input-phase not_started; delivery-phase unchanged; no financial effect or reverse operation reference.",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "allOf": [
                  {
                    "allOf": [
                      {
                        "allOf": [
                          {
                            "$ref": "#/components/schemas/Problem"
                          },
                          {
                            "properties": {
                              "code": {
                                "enum": [
                                  "invalid_request",
                                  "unauthenticated",
                                  "permission_denied",
                                  "authority_revoked",
                                  "resource_not_found",
                                  "rate_limited",
                                  "concurrency_limited",
                                  "dependency_unavailable",
                                  "internal_error",
                                  "limit_out_of_range"
                                ]
                              }
                            }
                          }
                        ]
                      },
                      {
                        "properties": {
                          "code": {
                            "const": "limit_out_of_range"
                          },
                          "status": {
                            "const": 422
                          },
                          "retry_action": {
                            "const": "do_not_retry"
                          },
                          "usage_state": {
                            "enum": [
                              "not_started",
                              "unchanged"
                            ]
                          }
                        }
                      },
                      {
                        "properties": {
                          "operation_id": {
                            "type": "null"
                          },
                          "status_path": {
                            "type": "null"
                          }
                        }
                      }
                    ]
                  },
                  {
                    "properties": {
                      "usage_state": {
                        "enum": [
                          "not_started",
                          "unchanged"
                        ]
                      },
                      "operation_id": {
                        "type": "null"
                      },
                      "status_path": {
                        "type": "null"
                      },
                      "code": {
                        "not": {
                          "enum": [
                            "operation_in_progress",
                            "operation_reconciling",
                            "completion_uncertain",
                            "budget_exhausted",
                            "funding_window_too_short"
                          ]
                        }
                      }
                    }
                  }
                ]
              },
              {
                "if": {
                  "properties": {
                    "code": {
                      "const": "limit_out_of_range"
                    },
                    "delivery_limit": {
                      "properties": {
                        "phase": {
                          "const": "delivery"
                        }
                      },
                      "required": [
                        "phase"
                      ]
                    }
                  },
                  "required": [
                    "code",
                    "delivery_limit"
                  ]
                },
                "then": {
                  "properties": {
                    "usage_state": {
                      "const": "unchanged"
                    }
                  }
                }
              }
            ]
          }
        }
      }
    },
    "429": {
      "description": "rate_limited; concurrency_limited",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Problem"
                  },
                  {
                    "properties": {
                      "code": {
                        "enum": [
                          "rate_limited",
                          "concurrency_limited"
                        ]
                      },
                      "status": {
                        "const": 429
                      }
                    }
                  }
                ]
              },
              {
                "properties": {
                  "usage_state": {
                    "enum": [
                      "not_started",
                      "unchanged"
                    ]
                  },
                  "operation_id": {
                    "type": "null"
                  },
                  "status_path": {
                    "type": "null"
                  },
                  "code": {
                    "not": {
                      "enum": [
                        "operation_in_progress",
                        "operation_reconciling",
                        "completion_uncertain",
                        "budget_exhausted",
                        "funding_window_too_short"
                      ]
                    }
                  }
                }
              }
            ]
          },
          "example": {
            "type": "urn:sustema:entity:problem:rate_limited",
            "title": "Throughput admission refused.",
            "status": 429,
            "code": "rate_limited",
            "request_id": "00000007-1111-4111-8111-000000000007",
            "operation_id": null,
            "retry_action": "wait_then_retry_same_operation",
            "usage_state": "not_started"
          }
        }
      },
      "x-error-codes": [
        "rate_limited",
        "concurrency_limited"
      ]
    },
    "500": {
      "description": "internal_error",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Problem"
                  },
                  {
                    "properties": {
                      "code": {
                        "enum": [
                          "internal_error"
                        ]
                      },
                      "status": {
                        "const": 500
                      }
                    }
                  }
                ]
              },
              {
                "properties": {
                  "usage_state": {
                    "enum": [
                      "not_started",
                      "unchanged"
                    ]
                  },
                  "operation_id": {
                    "type": "null"
                  },
                  "status_path": {
                    "type": "null"
                  },
                  "code": {
                    "not": {
                      "enum": [
                        "operation_in_progress",
                        "operation_reconciling",
                        "completion_uncertain",
                        "budget_exhausted",
                        "funding_window_too_short"
                      ]
                    }
                  }
                }
              }
            ]
          },
          "example": {
            "type": "urn:sustema:entity:problem:internal_error",
            "title": "Safe internal failure; no stack or protected payload.",
            "status": 500,
            "code": "internal_error",
            "request_id": "00000007-1111-4111-8111-000000000007",
            "operation_id": null,
            "retry_action": "wait_then_retry_same_operation",
            "usage_state": "not_started"
          }
        }
      },
      "x-error-codes": [
        "internal_error"
      ]
    },
    "503": {
      "description": "dependency_unavailable",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Problem"
                  },
                  {
                    "properties": {
                      "code": {
                        "enum": [
                          "dependency_unavailable"
                        ]
                      },
                      "status": {
                        "const": 503
                      }
                    }
                  }
                ]
              },
              {
                "properties": {
                  "usage_state": {
                    "enum": [
                      "not_started",
                      "unchanged"
                    ]
                  },
                  "operation_id": {
                    "type": "null"
                  },
                  "status_path": {
                    "type": "null"
                  },
                  "code": {
                    "not": {
                      "enum": [
                        "operation_in_progress",
                        "operation_reconciling",
                        "completion_uncertain",
                        "budget_exhausted",
                        "funding_window_too_short"
                      ]
                    }
                  }
                }
              }
            ]
          },
          "example": {
            "type": "urn:sustema:entity:problem:dependency_unavailable",
            "title": "Required policy, publication, ledger or search dependency unavailable.",
            "status": 503,
            "code": "dependency_unavailable",
            "request_id": "00000007-1111-4111-8111-000000000007",
            "operation_id": null,
            "retry_action": "wait_then_retry_same_operation",
            "usage_state": "not_started"
          }
        }
      },
      "x-error-codes": [
        "dependency_unavailable"
      ]
    },
    "default": {
      "description": "RFC 9457 problem; exact code/status/usage rules in errors.json. Current authority applies to all errors and replay.",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        },
        "WWW-Authenticate": {
          "schema": {
            "type": "string"
          },
          "description": "Bearer challenge for 401 responses."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Problem"
                  },
                  {
                    "properties": {
                      "code": {
                        "enum": [
                          "invalid_request",
                          "unauthenticated",
                          "permission_denied",
                          "authority_revoked",
                          "resource_not_found",
                          "rate_limited",
                          "concurrency_limited",
                          "dependency_unavailable",
                          "internal_error",
                          "limit_out_of_range"
                        ]
                      }
                    }
                  }
                ]
              },
              {
                "properties": {
                  "usage_state": {
                    "enum": [
                      "not_started",
                      "unchanged"
                    ]
                  },
                  "operation_id": {
                    "type": "null"
                  },
                  "status_path": {
                    "type": "null"
                  },
                  "code": {
                    "not": {
                      "enum": [
                        "operation_in_progress",
                        "operation_reconciling",
                        "completion_uncertain",
                        "budget_exhausted",
                        "funding_window_too_short"
                      ]
                    }
                  }
                }
              }
            ]
          }
        }
      }
    }
  },
  "x-permission": "usage.read",
  "x-billable": false,
  "x-cross-adapter-bound": {
    "operation": "getUsage",
    "rule": "#/x-delivery-bound-contract",
    "before_settlement": true
  },
  "description": "This pure owned read creates no new business effect or debit. Its failure reports only not_started/unchanged with null operation/status references. Existing underlying financial uncertainty is shown in the successful owned status envelope; unavailable read dependencies use the existing dependency_unavailable retry path. Never report a new reservation/settlement or invent a polling operation for this read. 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."
}

Referenced schemas

Includes schemas used by this operation and its shared or inherited parameters. Open a schema to follow its related definitions.

Shared parameter definitions
{
  "Cursor": {
    "name": "cursor",
    "in": "query",
    "required": false,
    "schema": {
      "type": "string",
      "maxLength": 4096,
      "x-profile-maxLength": "string_characters_max"
    },
    "description": "Opaque signed cursor bound to query, organisation, environment, profile, rights and index/publication generation."
  },
  "IdempotencyKey": {
    "name": "Idempotency-Key",
    "in": "header",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid",
      "maxLength": 36
    },
    "description": "Random UUID for one logical operation, including billed GETs. Same request/key/time replays without a second charge; ENTITY application semantics."
  },
  "Manifest": {
    "name": "manifest_id",
    "in": "query",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid",
      "maxLength": 36
    },
    "description": "Manifest returned by identity/search. A compatibility-bound follow-on read, not unrestricted historical query. Current rights and retention apply."
  },
  "MaxUnits": {
    "name": "Entity-Max-Units",
    "in": "header",
    "required": false,
    "schema": {
      "$ref": "#/components/schemas/Units"
    },
    "description": "Caller ceiling in the accepted offer atomic unit; cannot increase organisation authority."
  },
  "OperationCreated": {
    "name": "Entity-Operation-Created-At",
    "in": "header",
    "required": true,
    "schema": {
      "type": "string",
      "format": "date-time",
      "maxLength": 35
    },
    "description": "Original creation instant, unchanged on retry. New keys outside the profile admission/skew window are refused even after tombstone expiry."
  },
  "PageSize": {
    "name": "page_size",
    "in": "query",
    "required": false,
    "schema": {
      "type": "integer",
      "minimum": 1,
      "x-profile-maximum": "page_size_max"
    },
    "description": "Default and maximum from the active profile."
  },
  "ReceiptContext": {
    "name": "Entity-Receipt-Context",
    "in": "header",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid",
      "maxLength": 36
    },
    "description": "Readable own-organisation receipt containing the requested entity/manifest. Binds follow-on evidence/module reads to a known permitted result within its retention window; this is not unrestricted historical access."
  },
  "ServiceProfile": {
    "name": "Entity-Service-Profile",
    "in": "header",
    "required": true,
    "schema": {
      "type": "string",
      "maxLength": 4096,
      "x-profile-maxLength": "string_characters_max"
    },
    "description": "Accepted immutable service-profile revision; missing/unknown profiles cannot activate an operation."
  }
}
Inherited path parameters
[]

All API operations