List Usage Limit Plan Revisions

Read complete revision snapshots before choosing a rollback target. This endpoint never changes the Plan.

GET /v1/projects/:project_id/usage-limit-plans/:id/revisions

Authentication and scope

Requires usage_control:write. project_id is the owning project; id (when present) is its Plan ID. The API key supplies the tenant scope. Resources outside that tenant/project are not returned.

Request

There are no query parameters.

The request body is empty.

Response

HTTP 200.

{
  "plan_id": "ulp_pro",
  "current_revision": 1,
  "draft_revision": 0,
  "revisions": [
    {
      "id": "ulpv_pro_v1",
      "tenant_id": "t_001",
      "project_id": "proj_gateway",
      "plan_id": "ulp_pro",
      "name": "pro",
      "revision": 1,
      "status": "published",
      "title": "Pro daily budget",
      "description": "Default allowance",
      "published_at": 1784890000,
      "created_at": 1784889000,
      "updated_at": 1789722000,
      "rules": [
        {
          "id": "ulpr_budget_v1",
          "tenant_id": "t_001",
          "project_id": "proj_gateway",
          "plan_version_id": "ulpv_pro_v1",
          "limit_key": "ulrk_budget",
          "currency": "USD",
          "measure": "amount",
          "selector_type": "all",
          "period": "day",
          "limit_amount": "100",
          "timezone": "UTC",
          "action": "block",
          "webhook_event": "usage_limit.exceeded",
          "created_at": 1784890000,
          "updated_at": 1784890000
        }
      ],
      "referenced_by_count": 0
    }
  ]
}

Field	Meaning
plan_id	Requested Plan.
current_revision	Live pointer, or 0 before first publication.
draft_revision	Actual draft revision, or 0 if absent.
revisions	Complete history in descending revision order, with full inline rules. Includes drafts; the Portal only offers non-current published revisions as targets.

There is no pagination or query filter. Rules are loaded in bulk rather than with a query per revision.

Version fields: id (original version ID), tenant_id, project_id, plan_id, name, revision, status, title, optional description, original published_at (omitted for drafts), created_at, Plan updated_at, rules, and referenced_by_count. Detail/list reads can also include has_unpublished_changes and live_revision, derived from actual draft status. Reference counts are populated by detail/list reads; history and mutation responses do not calculate them. Each rule returns the business fields above plus its original id, plan_version_id, ownership, and creation/update timestamps. Empty optional fields may be omitted; timestamps are Unix seconds.

Behavior and errors

Missing/out-of-scope resources return 404, invalid inputs/lifecycle transitions 400, name/revision conflicts 409, insufficient permission 403, and internal/infrastructure failures 5xx. Failed write transactions leave Plan/history/rules unchanged; cache errors explicitly marked committed are the exception.

Lifecycle and window behavior · Create Usage Limit Plan · Get Usage Limit Plan · Update Usage Limit Plan Draft · Publish Usage Limit Plan · Roll Back Usage Limit Plan