Get Usage Limit Plan

Read the Plan, editable version, and the exact currently published version separately.

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

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",
    "tenant_id": "t_001",
    "project_id": "proj_gateway",
    "name": "pro",
    "title": "Pro daily budget",
    "description": "Default allowance",
    "status": "published",
    "current_revision": 1,
    "created_at": 1784889000,
    "updated_at": 1789722000
  },
  "version": {
    "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
  },
  "published_version": {
    "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
  }
}

plan contains Plan identity, tenant/project ownership, name, metadata, status, current_revision, and creation/update times. version selects a real draft when present, otherwise current. published_version always selects current and is omitted before first publication. After rollback preserves a draft, edit version.title/description; use published_version for live configuration.

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 · Update Usage Limit Plan Draft · Publish Usage Limit Plan · Roll Back Usage Limit Plan · List Usage Limit Plan Revisions