List Subject Routes

Returns active subject routes for one billing account in a project. Use this endpoint to render account routing screens or verify which usage subjects bill to an account.

GET /v1/projects/:project_id/account-subjects

Authentication

Authorization: Bearer <api-key>

Requires accounts read access.

Path Parameters

Field	Required	Description
project_id	Yes	Project that owns the account and subject routes.

Query Parameters

Field	Required	Description
account_id	Yes	Billing account ID in the same project.
subject_type	No	Exact subject type filter. Provide with subject_id to load one route 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/account-subjects?account_id=acct_org_001&subject_type=user&subject_id=user_123' \
  -H 'Authorization: Bearer <api-key>'

Response

{
  "account_subjects": [
    {
      "id": "asub_xxx",
      "tenant_id": "t_001",
      "project_id": "proj_gateway",
      "account_id": "acct_org_001",
      "subject_type": "user",
      "subject_id": "user_123",
      "effective_from": 1782720000,
      "created_at": 1782720000
    },
    {
      "id": "asub_yyy",
      "tenant_id": "t_001",
      "project_id": "proj_gateway",
      "account_id": "acct_org_001",
      "subject_type": "agent",
      "subject_id": "agent_789",
      "effective_from": 1782720100,
      "created_at": 1782720100
    }
  ],
  "total_count": 2,
  "limit": 100,
  "offset": 0
}

Notes

• The response only includes active routes for the requested account.
• When subject_type and subject_id are provided, pagination is ignored and the response contains either the matching route or an empty list.
• Results are paginated. Use total_count, limit, and offset to request subsequent pages.
• Subject routes define payer resolution. They do not include range limit settings; use List Usage Control Rules to read usage-control routes together with limits.