Get Subject Realtime Limits

Returns the subject-owned realtime usage-control snapshot across all active currencies and scopes. It resolves the subject route and active limit rules. It does not return wallet balance fields.

GET /v1/projects/:project_id/subject/realtime/limits

Authentication

Authorization: Bearer <api-key>

Path Parameters

Field	Required	Type	Description
project_id	Yes	string	Project that owns the subject route and limits.

Request

This endpoint has no request body. Supply its input as query parameters.

Field	Required	Type	Description
subject_type	Yes	string	Subject type, such as user or api_key.
subject_id	Yes	string	Subject ID whose usage-control snapshot is requested.

curl 'http://127.0.0.1:8080/v1/projects/proj_gateway/subject/realtime/limits?subject_type=user&subject_id=user_123' \
  -H 'Authorization: Bearer <api-key>'

Response

{
  "tenant_id": "t_001",
  "project_id": "proj_gateway",
  "account_id": "acct_org_001",
  "subject_type": "user",
  "subject_id": "user_123",
  "rule_account_id": "asub_user_123",
  "limits": [
    {
      "id": "racl_monthly_tokens",
      "rule_account_id": "asub_user_123",
      "subject_type": "user",
      "subject_id": "user_123",
      "currency": "USD",
      "metric_scope": "tokens",
      "selector_type": "metric",
      "selector_value": "input_tokens",
      "measure": "quantity",
      "period": "month",
      "window_id": "month:202607221023",
      "next_reset_at": 1787394180,
      "used_amount": "125000",
      "limit_amount": "1000000",
      "remaining_amount": "875000",
      "exceeded": false,
      "action": "block",
      "webhook_event": "usage.monthly_tokens_exceeded"
    },
    {
      "id": "racl_daily_key_requests",
      "rule_account_id": "asub_user_123",
      "subject_type": "user",
      "subject_id": "user_123",
      "dimension_key": "ap_key_id",
      "dimension_value": "key_abc",
      "currency": "USD",
      "metric_scope": "requests",
      "selector_type": "metric",
      "selector_value": "request_count",
      "measure": "quantity",
      "period": "day",
      "window_id": "2026-07-22",
      "next_reset_at": 1784755200,
      "used_amount": "8",
      "limit_amount": "100",
      "remaining_amount": "92",
      "exceeded": false,
      "action": "block",
      "webhook_event": "usage.daily_requests_exceeded"
    }
  ]
}

Field	Type	Description
tenant_id	string	Tenant that owns the subject route.
project_id	string	Project that owns the subject route.
account_id	string	Billing account resolved from the subject route.
subject_type	string	Resolved subject type.
subject_id	string	Resolved subject ID.
rule_account_id	string	Subject-route identity used by the snapshot.
limits	array	Realtime snapshot for every active rule that applies to this subject.

limits[] item

Field	Type	Description
id	string	Stable limit rule ID. Direct subject-route limits use the racl_* rule ID; Plan limits use the ulpr_* Plan rule ID.
rule_account_id	string	Subject-route identity that owns the rule.
subject_type / subject_id	string	Subject to which the rule applies.
dimension_key / dimension_value	string	Present when the rule is dimension-scoped.
currency	string	Rule currency for amount limits; quantity rules may use an empty or non-money currency context.
metric_scope	string	Metric scope represented by the limit.
selector_type / selector_value	string	Rule selector used to match usage.
measure	string	amount or quantity.
period	string	Limit period, such as hour, day, week, month, lifetime, or custom durations like 7d, 5h, 5 day, 2 week, or 5 month. All anchored windows start from the usage-limit anchor.
window_id	string	Current realtime limit window identifier.
next_reset_at	int64	Unix seconds for the current window end. Omitted for lifetime limits.
used_amount	decimal string	Usage accumulated in the current window.
limit_amount	decimal string	Frozen limit amount for the current window.
remaining_amount	decimal string	limit_amount - used_amount. It can be negative after an overage.
exceeded	boolean	Whether used amount is at least the frozen limit amount.
action	string	Configured control action, for example block or notify.
webhook_event	string	Optional webhook event emitted when the limit is crossed.

This is the canonical realtime snapshot endpoint for subject limits.