Skip to main content
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.
All calls use the Stigg REST API with your server-side API key in the 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

The featureIds 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

In tree mode, usageLimit, currentUsage, utilization, cadence, usagePeriodStart, and usagePeriodEnd are null, and rows carry no featureId or currencyId.

Response shape

A usage-mode response for featureIds=feature-ai-tokens:

Filtering

Filter by feature or currency

Pass featureIds 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 carries parentId, so you can reconstruct the full hierarchy from a flat response. Query in tree mode to get one row per entity: