List Usage Limit Plans

Returns Usage Limit Plans in one project. The default response contains active Plans only and excludes archived Plans.

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

Authentication

Requires an API key with usage_control:write.

Request

The request body is empty.

Path field	Required	Description
`project_id`	Yes	Project that owns the Usage Limit Plans.

Query field	Required	Description
`archived`	No	Set to `true` to return archived Plans instead of active Plans.
`published`	No	Set to `true` to return published Plans selectable for new route bindings.
`search`	No	Case-insensitive substring search across Plan ID, name, title, description.
`limit`	No	Page size. Defaults to `20`; maximum `100`.
`offset`	No	Zero-based page offset. Defaults to `0`.

Response

{
  "usage_limit_plans": [
    {
      "id": "ulpv_01J...",
      "tenant_id": "t_001",
      "project_id": "proj_gateway",
      "plan_id": "ulp_01J...",
      "name": "pro-monthly",
      "revision": 2,
      "status": "published",
      "title": "Pro monthly allowance",
      "description": "Default monthly control for Pro routes",
      "published_at": 1784890000,
      "created_at": 1784889000,
      "updated_at": 1784890100,
      "rules": [
        {
          "id": "ulpr_01J...",
          "plan_version_id": "ulpv_01J...",
          "limit_key": "monthly_tokens",
          "measure": "quantity",
          "selector_type": "unit",
          "selector_value": "tokens",
          "period": "month",
          "limit_amount": "1000000",
          "created_at": 1784889000,
          "updated_at": 1784890100
        }
      ]
    }
  ],
  "total_count": 1,
  "limit": 20,
  "offset": 0
}

Field	Description
`usage_limit_plans`	Page of Usage Limit Plan versions.
`total_count`	Total matching Plans before pagination.
`limit`	Applied page size.
`offset`	Applied zero-based page offset.

Behavior

Use archived=true for the archived Plan tab. Use published=true for route selectors that should only expose Plans available for new subject-route bindings. Archived Plans are excluded from published=true; when both flags are present, archived=true takes precedence.

Search is evaluated before pagination, so total_count reflects all matching Plans for the selected lifecycle view.