List Usage Control Rules

Returns the active usage control routes for one billing account in a project. Each returned rule includes the routed usage subject and its active range limits.

GET /v1/projects/:project_id/usage-control-rules

Authentication

Authorization: Bearer <api-key>

Path Parameters

Field	Required	Description
`project_id`	Yes	Project that owns the billing account, usage-control routes, and range limits.

Query Parameters

Field	Required	Description
`account_id`	Yes	Billing account ID in the same project. The response contains active usage-control routes for this account.
`subject_type`	No	Exact subject type filter. Provide with `subject_id` to load one usage-control route and its active limits without relying on pagination.
`subject_id`	No	Exact subject ID filter. Required when `subject_type` is provided.
`limit`	No	Page size. Defaults to `100`; maximum `500`.
`offset`	No	Zero-based page offset. Defaults to `0`.

Request Body

The request body is empty.

Example

curl 'http://127.0.0.1:8080/v1/projects/proj_gateway/usage-control-rules?account_id=acct_xxx&subject_type=user&subject_id=user_123' \
  -H 'Authorization: Bearer <api-key>'

Response

{
  "usage_control_rules": [
    {
      "rule_account": {
        "id": "racct_xxx",
        "tenant_id": "t_001",
        "project_id": "proj_gateway",
        "billing_account_id": "acct_xxx",
        "subject_type": "user",
        "subject_id": "user_123",
        "status": "active",
        "created_at": 1782720000,
        "updated_at": 1782720000
      },
      "limits": [
        {
          "id": "racl_xxx",
          "tenant_id": "t_001",
          "project_id": "proj_gateway",
          "rule_kind": "subject_route",
          "rule_id": "racct_xxx",
          "currency": "USD",
          "metric_scope": "tokens",
          "period": "week",
          "limit_amount": "1000000",
          "timezone": "Asia/Shanghai",
          "action": "block",
          "webhook_event": "usage.weekly_tokens_exceeded",
          "status": "active",
          "created_at": 1782720000,
          "updated_at": 1782720000
        }
      ]
    }
  ],
  "total_count": 1,
  "limit": 100,
  "offset": 0
}

Notes

This endpoint currently lists active rules for one billing account. Pass account_id to choose the account.
When subject_type and subject_id are provided, pagination is ignored and the response contains either the matching route with its active limits or an empty list.
Results are paginated. Use total_count, limit, and offset to request subsequent pages.
The response uses the same per-rule shape as Create Usage Control Rule, wrapped in usage_control_rules.