Skip to main content
GET
/
api
/
v1-beta
/
customers
/
{id}
/
governance
JavaScript
import Stigg from '@stigg/typescript';

const client = new Stigg({
  apiKey: process.env['STIGG_API_KEY'], // This is the default and can be omitted
});

const response = await client.v1.events.beta.customers.retrieveGovernance('id');

console.log(response.data);
{
  "data": [
    {
      "entityId": "team-eng",
      "parentId": "org-acme",
      "entityType": "team",
      "featureId": "ai-tokens",
      "scopeEntityIds": [],
      "usageLimit": 1000,
      "currentUsage": 820,
      "utilization": 0.82,
      "cadence": "P1M",
      "usagePeriodStart": "2026-05-01T00:00:00.000Z",
      "usagePeriodEnd": "2026-06-01T00:00:00.000Z"
    },
    {
      "entityId": "team-eng",
      "parentId": "org-acme",
      "entityType": "team",
      "featureId": "ai-tokens",
      "scopeEntityIds": [
        "model-a"
      ],
      "usageLimit": 500,
      "currentUsage": 130,
      "utilization": 0.26,
      "cadence": "P1M",
      "usagePeriodStart": "2026-05-01T00:00:00.000Z",
      "usagePeriodEnd": "2026-06-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "next": null
  }
}

Authorizations

​
X-API-KEY
string
header
required

Server API Key

Headers

​
X-ACCOUNT-ID
string

Account ID — optional when authenticating with a user JWT (Bearer token); falls back to the user's first membership. Ignored for API-key auth.

​
X-ENVIRONMENT-ID
string

Environment ID — required when authenticating with a user JWT (Bearer token) on environment-scoped endpoints. Ignored for API-key auth (env is intrinsic to the key).

Path Parameters

​
id
string
required

The customer external id.

Required string length: 1 - 255
Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$

Query Parameters

​
limit
integer
default:20

Maximum number of items to return

Required range: 1 <= x <= 100
​
after
string

Return items that come after this cursor

Maximum string length: 255
​
featureIds
string[]

Feature ids to include, repeated per value (e.g. ?featureIds=ai-tokens&featureIds=seats). Omit both featureIds and currencyIds for tree mode — every node in the hierarchy with no usage configuration attached.

​
currencyIds
string[]

Currency ids to include, repeated per value (e.g. ?currencyIds=credits). Omit both featureIds and currencyIds for tree mode.

​
sortBy
enum<string>
default:utilization

Sort key: utilization (default, cross-capability-safe), currentUsage, usageLimit, scopeSize, id, or createdAt.

Available options:
utilization,
currentUsage,
usageLimit,
scopeSize,
id,
createdAt
​
order
enum<string>
default:desc

Sort direction: asc or desc (default desc).

Available options:
asc,
desc
​
scope
enum<string>
default:all

Filter by configuration scope: all (default), nodeWide ([] only), or scoped (non-empty only).

Available options:
all,
nodeWide,
scoped
​
minUtilization
number

Only nodes with utilization ≥ this value (e.g. 0.8 for ≥80%, 1 for at/over limit).

Required range: x >= 0
​
entityTypeIds
string[]

Filter to one or more entity types, repeated per value (e.g. ?entityTypeIds=team&entityTypeIds=user).

​
entityIdSearch
string

Case-insensitive substring match on the entity id (%/_ matched literally).

Required string length: 1 - 255

Response

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

Paginated list of governance tree nodes, each with its usage configuration and current usage.

​
data
GovernanceNode · object[]
required
​
pagination
object
required