GET /api/v1-beta/customers/:id/governance
Returns a paginated, sortable, filterable view of a customer’s governance tree. Each node comes with its hierarchy position, budget configuration, and current usage. Use this endpoint to power dashboards, admin UIs, and leaderboards.
Usage figures may lag the live counter by a few seconds. This endpoint never gates — use Check for real-time gate decisions.
X-API-KEY header. In TypeScript, use client.v1Beta.customers.governance.list(customerId, params) with the client from Setting up. It pages through the results for you.
Usage mode and tree mode
ThefeatureIds and currencyIds filters decide what the query returns.
Use usage mode for dashboards and leaderboards. Use tree mode to render the hierarchy itself.
Usage mode
Tree mode
usageLimit, currentUsage, utilization, cadence, usagePeriodStart, and usagePeriodEnd are null, and rows carry no featureId or currencyId.
Response shape
A usage-mode response forfeatureIds=feature-ai-tokens:
Filtering
Filter by feature or currency
PassfeatureIds for feature budgets and currencyIds for credit budgets. For several values, repeat the parameter (featureIds=a&featureIds=b) or comma-separate them (featureIds=a,b). You can combine both in one request.
Filter by entity type
Filter by scope
Filter by utilization
Search by entity ID or name
entityIdSearch is a case-insensitive substring match on the entity ID or its display name. % and _ match literally.
Sorting
Pagination
The query endpoint uses cursor pagination.limit defaults to 20, up to a maximum of 100.
pagination.next is null when you have reached the last page. To go back a page, pass pagination.prev as before; it’s null on the first page.
Rebuilding the tree client-side
Each row carriesparentId, so you can reconstruct the full hierarchy from a flat response. Query in tree mode to get one row per entity: