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

# 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.
    - `parentId` string, nullable, required — External id of the parent entity in the tree; `null` for a root. Use it to rebuild the tree.
    - `entityType` string, required — External id of the entity type (e.g. `team`, `user`).
    - `featureId` string — The metered feature refId (present when the configured capability is a feature).
    - `currencyId` string — The metered currency refId (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` 'MONTH', nullable, required — Usage-reset cadence. Currently only `MONTH` is supported.
    - `usagePeriodStart` string, date-time, nullable, required — Start of the cadence period the usage snapshot belongs to; `null` once the period has rolled over.
    - `usagePeriodEnd` string, date-time, nullable, required — Exclusive end of the cadence period — when usage resets; `null` once the period has rolled over.
  - `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.

## Changes

- **2026-06-18** `de96c0c4633a` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/stiggio/apis/stigg-api/changes/api/v1-beta/customers/:id/governance/get.md)

---

[API](https://skmtc.dev/stiggio/apis/stigg-api.md) · [All operations](https://skmtc.dev/stiggio/apis/stigg-api/llms.txt) · [OpenAPI document](https://skmtc.dev/stiggio/apis/stigg-api/revisions/de96c0c4633a?raw)