Reset Usage Limits

Creates a reset operation for realtime usage-limit projections. It does not change UsageEvent facts, wallet balances, invoices, ledger entries, or past webhooks.

POST /v1/projects/:project_id/usage-limit-resets

Authentication

Requires an API key with usage_control:write.

Request Body

{
  "scope": "billing_account",
  "target_id": "acct_org_001",
  "reason": "Customer-approved quota reset"
}

Field	Required	Description
scope	No	Reset scope. Defaults to project. Supported values are project, billing_account, usage_limit_plan, and subject_route.
target_id	Conditional	Omit for project. Required for every other scope; it is the account ID, Usage Limit Plan ID, or subject-route ID in this project.
reason	No	Audit note for the reset operation.

Scope behavior

Scope	target_id	Affected realtime usage limits
project	Omit	Every route in the project.
billing_account	Billing account ID	Routes that debit this account in the project.
usage_limit_plan	Usage Limit Plan ID	Routes currently configured to use this Plan.
subject_route	Subject-route ID	Only this route.

The API verifies that a non-project target belongs to the current tenant and project. A Plan target must be published.

Response

{
  "id": "ulr_01J...",
  "tenant_id": "t_001",
  "project_id": "proj_gateway",
  "scope": "billing_account",
  "target_id": "acct_org_001",
  "generation": 42,
  "effective_occurred_at": 1784894400,
  "requested_by": "tenant_admin",
  "reason": "Customer-approved quota reset",
  "created_at": 1784894400
}

generation is unique within the project, including across all reset scopes, and is included in the lazy Redis accumulator key. Project and Plan boundaries are shared generation states. An account reset updates the bounded set of active routes for that account; a subject-route reset updates one route. Those two scopes also delete their known current accumulator hashes as a memory cleanup; they never scan a project-wide keyspace.

Event-time semantics

For one route, Meterry reads the applicable project and (when the route uses a Plan) Plan generation state, plus the account and subject-route reset snapshots carried by the route. It uses the one with the latest effective_occurred_at (breaking an exact tie with the larger generation).

Only usage with UsageEvent.occurred_at >= effective_occurred_at is rebuilt into that generation. A historical event reported late still belongs to its historical limit window and is not added back after a reset. A cold accumulator rebuild starts from:

max(current_window_start, effective_occurred_at)

This endpoint does not emit usage_limit.recovered. Reset is the business system’s action, so downstream access control should handle the response and update its own state directly.

Read the latest operation for a scope

GET /v1/projects/:project_id/usage-limit-resets/latest
GET /v1/projects/:project_id/usage-limit-resets/latest?scope=billing_account&target_id=acct_org_001

Without query parameters, the endpoint returns the latest project reset. Pass both scope and target_id for a non-project scope.

Idempotency

Send Idempotency-Key for retryable requests. It is scoped to the tenant and project; retrying the same key returns the original reset operation.