Create Budget Lease

Creates an active one-time budget for a task run. A Budget Lease is bound to an existing stable subject route and its billing account; it is not an account subject and does not add a long-lived route row.

POST /v1/projects/:project_id/budget-leases

Authentication

Requires an API key with usage_control:write.

Request Body

{
  "run_id": "run_01J...",
  "billing_account_id": "acct_customer_001",
  "subject_type": "user",
  "subject_id": "user_123",
  "currency": "USD",
  "limit_amount": "5.00",
  "action": "block",
  "webhook_event": "usage.task_budget_exhausted"
}

Field	Required	Description
run_id	Yes	Caller-generated, never-reused task run ID. It is idempotent within the project when the lease attributes are identical.
billing_account_id	Yes	Payer account. It must be the account resolved by the stable subject route.
subject_type, subject_id	Yes	Existing durable subject route used for attribution and payer resolution.
currency	Yes	Currency of the one-time amount budget.
limit_amount	Yes	Positive decimal budget. Use a JSON string for decimal precision.
action	No	block (default) or notify. Included in the exhaustion webhook.
webhook_event	No	Optional customer event name used to select webhook subscriptions.

The response is the created BudgetLease, with status: "active".

Use the lease on usage events

Attach the returned lease ID to every event for the run:

{
  "x-usage-control": {
    "budget_lease_id": "ble_..."
  }
}

Meterry snapshots this ID on the normalized usage event, debits the shared billing account normally, and atomically accumulates the rated amount against the Lease’s fixed lifetime window. Every new rated usage version that leaves the Lease at or above its cap emits budget_lease.exhausted with data.budget_lease.id, data.budget_lease.run_id, and the configured action; replays of the same version are deduplicated.

See Stop a Task at Its Budget for the full integration flow.