---
title: "Get a list of governance nodes"
method: GET
path: "/api/v1-beta/customers/{id}/governance"
tags: ["Governance Hierarchy"]
---

# Get a list of governance nodes

`GET /api/v1-beta/customers/{id}/governance`

Queries the customer's governance hierarchy tree, returning a cursor-paginated list of nodes with their usage configuration (limit, cadence, scope) and current usage, sortable and filterable by usage. Each node carries `parentId` so the tree can be rebuilt client-side. Usage is read from a periodically-refreshed read model and never gates access.

## Path parameters

- `id` string, required

## Query parameters

- `limit` integer
- `after` string
- `featureIds` string[]
- `currencyIds` string[]
- `sortBy` 'utilization' | 'currentUsage' | 'usageLimit' | 'scopeSize' | 'id' | 'createdAt'
- `order` 'asc' | 'desc'
- `scope` 'all' | 'nodeWide' | 'scoped'
- `minUtilization` number
- `entityTypeIds` string[]
- `entityIdSearch` string

## Headers

- `X-ACCOUNT-ID` string
- `X-ENVIRONMENT-ID` string

## Response `200`

A paginated list of governance tree nodes with usage configuration and current usage.

- GovernanceQueryResponseDto — Paginated list of governance tree nodes, each with its usage configuration and current usage.
  - `data` object[], required
    - `entityId` string, required — External id of the entity at this node.
    - `displayName` string, nullable, required — Human-readable name of the entity, or null when none is set (display the entity id instead).
    - `parentId` string, nullable, required — External id of the parent entity in the tree. `null` means the entity is either a root or not yet placed in the hierarchy — placement rides on an assignment, so an entity with no limits set has no parent yet. Both render at the top level; use it to rebuild the tree.
    - `entityTypeId` string, required — External id of the entity type (e.g. `team`, `user`).
    - `featureId` string — The metered feature ID (present when the configured capability is a feature).
    - `currencyId` string — The metered currency ID (present when the configured capability is a credit currency).
    - `scopeEntityIds` string[], required — The configuration scope (entity ids). Empty is the node-wide configuration; a non-empty set is a dimension-scoped sub-configuration.
    - `usageLimit` number, nullable, required — Hard usage limit for this node per cadence period.
    - `currentUsage` number, nullable, required — Usage consumed in the current cadence period (may lag the live counter by a short interval).
    - `utilization` number, nullable, required — `currentUsage / usageLimit` (1 when usageLimit is 0 — always at limit). The cross-capability-safe sort key.
    - `cadence` string, nullable, required — Usage-reset cadence as an ISO-8601 single-unit duration, e.g. `P1M`, `P30D`, `PT1M`; `null` when the node has no usage configuration.
    - `usagePeriodStart` string, date-time, nullable, required — Start of the cadence period in progress now, derived from the cadence and the assignment anchor — it stays correct across a rollover. `null` when the node has no usage configuration, or when a stored cadence cannot be parsed.
    - `usagePeriodEnd` string, date-time, nullable, required — Exclusive end of the cadence period in progress now — when usage resets. `null` when the node has no usage configuration, or when a stored cadence cannot be parsed.
  - `pagination` object, required
    - `next` string, nullable, required — Cursor for fetching the next page of results, or null if no additional pages exist

## Other responses

- `400` — bad request.
- `401` — User is not authenticated.
- `403` — User is not allowed to access this resource.
- `429` — Too many requests.

---

[API](https://skmtc.net/stiggio/apis/stigg-api.md) · [All operations](https://skmtc.net/stiggio/apis/stigg-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stiggio/stigg-api/revisions/ffc977f1c07e/schema)