Governance query - Stigg Documentation

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 are served from a periodically-refreshed read model and may lag the live counter by a few minutes. 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.

Usage mode and tree mode

The featureIds and currencyIds filters decide what the query returns.

Mode	Request	Rows returned
Usage mode	Pass `featureIds`, `currencyIds`, or both	One row per budget on the requested features or currencies, with its limit, cadence, and current usage
Tree mode	Omit both `featureIds` and `currencyIds`	One row per entity in the hierarchy, with no usage configuration attached

Use usage mode for dashboards and leaderboards. Use tree mode to render the hierarchy itself.

Usage mode

const res = await fetch(
  'https://api.stigg.io/api/v1-beta/customers/cus-acme/governance?featureIds=feature_ai_tokens&limit=20',
  { headers: { 'X-API-KEY': process.env.STIGG_SERVER_API_KEY! } },
);
const { data, pagination } = await res.json();
// data: GovernanceNode[]
// pagination: { next: string | null }

curl "https://api.stigg.io/api/v1-beta/customers/cus-acme/governance?featureIds=feature_ai_tokens&limit=20" \
  -H "X-API-KEY: <SERVER_API_KEY>"

Tree mode

const res = await fetch('https://api.stigg.io/api/v1-beta/customers/cus-acme/governance?limit=20', {
  headers: { 'X-API-KEY': process.env.STIGG_SERVER_API_KEY! },
});
const { data, pagination } = await res.json();

curl "https://api.stigg.io/api/v1-beta/customers/cus-acme/governance?limit=20" \
  -H "X-API-KEY: <SERVER_API_KEY>"

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:

{
  "data": [
    {
      "entityId": "team-eng",
      "displayName": "Engineering",
      "parentId": "org-acme",
      "entityTypeId": "team",
      "featureId": "feature_ai_tokens",
      "scopeEntityIds": [],
      "usageLimit": 200000,
      "currentUsage": 164000,
      "utilization": 0.82,
      "cadence": "P1M",
      "usagePeriodStart": "2026-05-01T00:00:00.000Z",
      "usagePeriodEnd": "2026-06-01T00:00:00.000Z"
    },
    {
      "entityId": "team-eng",
      "displayName": "Engineering",
      "parentId": "org-acme",
      "entityTypeId": "team",
      "featureId": "feature_ai_tokens",
      "scopeEntityIds": ["model-gpt4o"],
      "usageLimit": 10000,
      "currentUsage": 2600,
      "utilization": 0.26,
      "cadence": "P1M",
      "usagePeriodStart": "2026-05-01T00:00:00.000Z",
      "usagePeriodEnd": "2026-06-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "next": "eyJpZCI6InRlYW0tZW5nIn0="
  }
}

Field	Description
`entityId`	External ID of the entity (hierarchy node).
`displayName`	Human-readable name of the entity, or `null` when none is set. Show `entityId` instead when it is `null`.
`parentId`	External ID of the parent entity. `null` means the entity is a root, or has not been placed in the hierarchy yet. An entity is placed through an assignment, so an entity with no assignments has no parent. Use this field to rebuild the tree client-side.
`entityTypeId`	External ID of the entity type (e.g., `org`, `team`, `user`).
`featureId`	The metered feature this budget governs. Present when the budget is on a feature.
`currencyId`	The credit currency this budget governs. Present when the budget is on a currency.
`scopeEntityIds`	The configuration scope. `[]` is the node-wide budget; a non-empty set is a dimension-scoped sub-budget.
`usageLimit`	Hard usage limit per cadence period.
`currentUsage`	Usage consumed in the current cadence period (may lag by minutes).
`utilization`	`currentUsage / usageLimit`, and `1` when `usageLimit` is `0`. `null` when the node has no usage configuration.
`cadence`	ISO-8601 reset cadence (e.g., `P1M`).
`usagePeriodStart`	Start of the cadence period in progress now.
`usagePeriodEnd`	When usage resets (exclusive).

Filtering

Filter by feature or currency

Pass featureIds for feature budgets and currencyIds for credit budgets. Repeat each parameter once per value. You can combine both in one request.

const res = await fetch(
  'https://api.stigg.io/api/v1-beta/customers/cus-acme/governance?featureIds=feature_ai_tokens&featureIds=feature_api_calls',
  { headers: { 'X-API-KEY': process.env.STIGG_SERVER_API_KEY! } },
);
const { data } = await res.json();

curl "https://api.stigg.io/api/v1-beta/customers/cus-acme/governance?featureIds=feature_ai_tokens&featureIds=feature_api_calls" \
  -H "X-API-KEY: <SERVER_API_KEY>"

# Credit budgets
curl "https://api.stigg.io/api/v1-beta/customers/cus-acme/governance?currencyIds=credits" \
  -H "X-API-KEY: <SERVER_API_KEY>"

Filter by entity type

const res = await fetch(
  'https://api.stigg.io/api/v1-beta/customers/cus-acme/governance?entityTypeIds=team&entityTypeIds=user',
  { headers: { 'X-API-KEY': process.env.STIGG_SERVER_API_KEY! } },
);
const { data } = await res.json();

curl "https://api.stigg.io/api/v1-beta/customers/cus-acme/governance?entityTypeIds=team&entityTypeIds=user" \
  -H "X-API-KEY: <SERVER_API_KEY>"

Filter by scope

`scope` value	Rows included
`'all'` (default)	All rows
`'nodeWide'`	Only node-wide budgets (`scopeEntityIds: []`)
`'scoped'`	Only dimension-scoped sub-budgets

const res = await fetch(
  'https://api.stigg.io/api/v1-beta/customers/cus-acme/governance?scope=nodeWide',
  { headers: { 'X-API-KEY': process.env.STIGG_SERVER_API_KEY! } },
);
const { data } = await res.json();

curl "https://api.stigg.io/api/v1-beta/customers/cus-acme/governance?scope=nodeWide" \
  -H "X-API-KEY: <SERVER_API_KEY>"

Filter by utilization

// Entities at ≥ 80% utilization
const nearLimitRes = await fetch(
  'https://api.stigg.io/api/v1-beta/customers/cus-acme/governance?minUtilization=0.8',
  { headers: { 'X-API-KEY': process.env.STIGG_SERVER_API_KEY! } },
);
const { data: nearLimit } = await nearLimitRes.json();

curl "https://api.stigg.io/api/v1-beta/customers/cus-acme/governance?minUtilization=0.8" \
  -H "X-API-KEY: <SERVER_API_KEY>"

Search by entity ID or name

entityIdSearch is a case-insensitive substring match on the entity ID or its display name. % and _ match literally.

const res = await fetch(
  'https://api.stigg.io/api/v1-beta/customers/cus-acme/governance?entityIdSearch=team',
  { headers: { 'X-API-KEY': process.env.STIGG_SERVER_API_KEY! } },
);
const { data } = await res.json();

curl "https://api.stigg.io/api/v1-beta/customers/cus-acme/governance?entityIdSearch=team" \
  -H "X-API-KEY: <SERVER_API_KEY>"

Sorting

`sortBy` value	Description
`'utilization'` (default)	`currentUsage / usageLimit`
`'currentUsage'`	Raw usage count
`'usageLimit'`	Configured limit
`'scopeSize'`	Node-wide rows first, then scoped by set size
`'id'`	Entity ID alphabetical
`'createdAt'`	Creation timestamp

// Teams closest to their limit, descending
const res = await fetch(
  'https://api.stigg.io/api/v1-beta/customers/cus-acme/governance?featureIds=feature_ai_tokens&entityTypeIds=team&sortBy=utilization&order=desc&limit=20',
  { headers: { 'X-API-KEY': process.env.STIGG_SERVER_API_KEY! } },
);
const { data } = await res.json();

curl "https://api.stigg.io/api/v1-beta/customers/cus-acme/governance?featureIds=feature_ai_tokens&entityTypeIds=team&sortBy=utilization&order=desc" \
  -H "X-API-KEY: <SERVER_API_KEY>"

Pagination

The query endpoint uses forward-only cursor pagination. limit defaults to 20, up to a maximum of 100.

async function* queryAllNodes(customerId: string) {
  let after: string | undefined;
  const apiKey = process.env.STIGG_SERVER_API_KEY!;

  do {
    const url = new URL(`https://api.stigg.io/api/v1-beta/customers/${customerId}/governance`);
    url.searchParams.set('limit', '50');
    if (after) url.searchParams.set('after', after);

    const res = await fetch(url.toString(), { headers: { 'X-API-KEY': apiKey } });
    const page = await res.json();
    yield* page.data;
    after = page.pagination.next ?? undefined;
  } while (after);
}

# First page
curl "https://api.stigg.io/api/v1-beta/customers/cus-acme/governance?limit=10" \
  -H "X-API-KEY: <SERVER_API_KEY>"

# Next page — pass pagination.next from the previous response
curl "https://api.stigg.io/api/v1-beta/customers/cus-acme/governance?limit=10&after=<CURSOR>" \
  -H "X-API-KEY: <SERVER_API_KEY>"

pagination.next is null when you have reached the last 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:

type QueryRow = { entityId: string; parentId: string | null; [key: string]: unknown };
type TreeNode = QueryRow & { children: TreeNode[] };

function buildTree(rows: QueryRow[]): TreeNode[] {
  const byId = new Map<string, TreeNode>(
    rows.map(r => [r.entityId, { ...r, children: [] }])
  );
  const roots: TreeNode[] = [];

  for (const node of byId.values()) {
    if (node.parentId && byId.has(node.parentId)) {
      byId.get(node.parentId)!.children.push(node);
    } else {
      roots.push(node);
    }
  }

  return roots;
}

Introduction

Get started

Usage metering

Credits

Entitlements and access enforcement

Governance

AI agents

Architecture and deployment

Pricing and packaging

Customers, subscriptions and contracts

Workflows

Widgets

Developer tools

Account management

Security & compliance

Query the governance tree

Usage mode and tree mode

Usage mode

Tree mode

Response shape

Filtering

Filter by feature or currency

Filter by entity type

Filter by scope

Filter by utilization

Search by entity ID or name

Sorting

Rebuilding the tree client-side

​Usage mode and tree mode

​Usage mode

​Tree mode

​Response shape

​Filtering

​Filter by feature or currency

​Filter by entity type

​Filter by scope

​Filter by utilization

​Search by entity ID or name

​Sorting

​Pagination

​Rebuilding the tree client-side

Usage mode and tree mode

Usage mode

Tree mode

Response shape

Filtering

Filter by feature or currency

Filter by entity type

Filter by scope

Filter by utilization

Search by entity ID or name

Sorting

Pagination

Rebuilding the tree client-side