> ## Documentation Index > Fetch the complete documentation index at: https://docs.stigg.io/llms.txt > Use this file to discover all available pages before exploring further. # Get a list of governance nodes > 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. ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/stigg/openapi.documented.yml get /api/v1-beta/customers/{id}/governance openapi: 3.0.0 info: title: Stigg API description: Stigg API documentation version: 7.90.2 contact: {} servers: - url: https://api.stigg.io description: Production security: - ApiKeyAuth: [] tags: - name: Customers description: Operations related to customers - name: Subscriptions description: Operations related to subscriptions - name: Coupons description: Operations related to coupons - name: Bulk Import description: Operations related to import of customers and subscriptions - name: Usage description: Operations related to usage & metering - name: Promotional Entitlements description: Operations related to promotional entitlements - name: Products description: Operations related to products - name: Features description: Operations related to features - name: Addons description: Operations related to addons - name: Plans description: Operations related to plans - name: Credit grants description: Operations related to credit grants - name: Credit ledger description: Operations related to credit ledger - name: Custom currencies description: Operations related to custom currencies paths: /api/v1-beta/customers/{id}/governance: get: tags: - Governance Hierarchy summary: Get a list of governance nodes description: >- 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. operationId: GovernanceController_query parameters: - name: id required: true in: path description: The customer ID. schema: minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$ type: string - name: limit required: false in: query description: Maximum number of items to return schema: minimum: 1 maximum: 100 default: 20 type: integer - name: after required: false in: query description: Return items that come after this cursor schema: maxLength: 255 type: string - name: featureIds required: false in: query description: >- 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. schema: type: array items: type: string - name: currencyIds required: false in: query description: >- Currency ids to include, repeated per value (e.g. `?currencyIds=credits`). Omit both featureIds and currencyIds for tree mode. schema: type: array items: type: string - name: sortBy required: false in: query description: >- Sort key: `utilization` (default, cross-capability-safe), `currentUsage`, `usageLimit`, `scopeSize`, `id`, or `createdAt`. schema: default: utilization enum: - utilization - currentUsage - usageLimit - scopeSize - id - createdAt type: string - name: order required: false in: query description: 'Sort direction: `asc` or `desc` (default `desc`).' schema: default: desc enum: - asc - desc type: string - name: scope required: false in: query description: >- Filter by configuration scope: `all` (default), `nodeWide` (`[]` only), or `scoped` (non-empty only). schema: default: all enum: - all - nodeWide - scoped type: string - name: minUtilization required: false in: query description: >- Only nodes with utilization ≥ this value (e.g. 0.8 for ≥80%, 1 for at/over limit). schema: type: number minimum: 0 - name: entityTypeIds required: false in: query description: >- Filter to one or more entity types, repeated per value (e.g. `?entityTypeIds=team&entityTypeIds=user`). schema: type: array items: type: string - name: entityIdSearch required: false in: query description: >- Case-insensitive substring match on the entity id (`%`/`_` matched literally). schema: minLength: 1 maxLength: 255 type: string - name: X-ACCOUNT-ID in: header description: >- Account ID — optional when authenticating with a user JWT (Bearer token); falls back to the user's first membership. Ignored for API-key auth. required: false schema: type: string - name: X-ENVIRONMENT-ID in: header description: >- 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). required: false schema: type: string responses: '200': description: >- A paginated list of governance tree nodes with usage configuration and current usage. content: application/json: schema: $ref: '#/components/schemas/GovernanceQueryResponseDto' examples: default: value: data: - entityId: team-eng parentId: org-acme entityTypeId: 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 entityTypeId: 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 '400': description: bad request. content: application/json: schema: $ref: '#/components/schemas/BadInputErrorResponseDto' '401': description: User is not authenticated. content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedErrorResponseDto' '403': description: User is not allowed to access this resource. content: application/json: schema: $ref: '#/components/schemas/ForbiddenErrorResponseDto' '429': description: Too many requests. content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponseDto' x-codeSamples: - lang: JavaScript source: >- 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); - lang: Python source: |- import os from stigg import Stigg client = Stigg( api_key=os.environ.get("STIGG_API_KEY"), # This is the default and can be omitted ) response = client.v1.events.beta.customers.retrieve_governance( id="id", ) print(response.data) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/stiggio/stigg-go\"\n\t\"github.com/stiggio/stigg-go/option\"\n)\n\nfunc main() {\n\tclient := stigg.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.V1.Events.Beta.Customers.GetGovernance(\n\t\tcontext.TODO(),\n\t\t\"id\",\n\t\tstigg.V1EventBetaCustomerGetGovernanceParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Data)\n}\n" - lang: Java source: >- package io.stigg.example; import io.stigg.client.StiggClient; import io.stigg.client.okhttp.StiggOkHttpClient; import io.stigg.models.v1.events.beta.customers.CustomerRetrieveGovernanceParams; import io.stigg.models.v1.events.beta.customers.CustomerRetrieveGovernanceResponse; public final class Main { private Main() {} public static void main(String[] args) { StiggClient client = StiggOkHttpClient.fromEnv(); CustomerRetrieveGovernanceResponse response = client.v1().events().beta().customers().retrieveGovernance("id"); } } - lang: Ruby source: |- require "stigg" stigg = Stigg::Client.new(api_key: "My API Key") response = stigg.v1.events.beta.customers.retrieve_governance("id") puts(response) - lang: C# source: >- using System; using Stigg.Client; using Stigg.Client.Models.V1.Events.Beta.Customers; StiggClient client = new(); CustomerRetrieveGovernanceParams parameters = new() { ID = "id" }; var response = await client.V1.Events.Beta.Customers.RetrieveGovernance(parameters); Console.WriteLine(response); - lang: CLI source: |- stigg v1:events:beta:customers retrieve-governance \ --api-key 'My API Key' \ --id id components: schemas: GovernanceQueryResponseDto: type: object properties: data: type: array items: type: object properties: entityId: type: string maxLength: 255 description: External id of the entity at this node. parentId: type: string maxLength: 255 description: >- External id of the parent entity in the tree; `null` for a root. Use it to rebuild the tree. nullable: true entityTypeId: type: string maxLength: 255 description: External id of the entity type (e.g. `team`, `user`). featureId: type: string maxLength: 255 description: >- The metered feature ID (present when the configured capability is a feature). currencyId: type: string maxLength: 255 description: >- The metered currency ID (present when the configured capability is a credit currency). scopeEntityIds: type: array items: type: string maxLength: 255 description: >- The configuration scope (entity ids). Empty is the node-wide configuration; a non-empty set is a dimension-scoped sub-configuration. description: >- The configuration scope (entity ids). Empty is the node-wide configuration; a non-empty set is a dimension-scoped sub-configuration. usageLimit: type: number description: Hard usage limit for this node per cadence period. nullable: true currentUsage: type: number description: >- Usage consumed in the current cadence period (may lag the live counter by a short interval). nullable: true utilization: type: number description: >- `currentUsage / usageLimit` (1 when usageLimit is 0 — always at limit). The cross-capability-safe sort key. nullable: true cadence: type: string maxLength: 255 description: >- Usage-reset cadence as an ISO-8601 single-unit duration, e.g. `P1M`, `P30D`, `PT1M`; `null` when the node has no usage configuration. nullable: true usagePeriodStart: type: string format: date-time description: >- Start of the cadence period the usage snapshot belongs to; `null` once the period has rolled over. nullable: true usagePeriodEnd: type: string format: date-time description: >- Exclusive end of the cadence period — when usage resets; `null` once the period has rolled over. nullable: true required: - entityId - parentId - entityTypeId - scopeEntityIds - usageLimit - currentUsage - utilization - cadence - usagePeriodStart - usagePeriodEnd title: GovernanceNode description: >- A node of the governance hierarchy tree with its usage configuration (limit, cadence, scope) and current usage. Usage is read from a periodically-refreshed read model and may lag the live counter by a short interval; it never gates access. pagination: type: object properties: next: type: string maxLength: 255 description: >- Cursor for fetching the next page of results, or null if no additional pages exist nullable: true required: - next required: - data - pagination title: GovernanceQueryResponse description: >- Paginated list of governance tree nodes, each with its usage configuration and current usage. BadInputErrorResponseDto: type: object properties: message: type: string code: type: string enum: - BadUserInput - DuplicateIntegrationNotAllowed - EntityIsArchivedError - IntegrityViolation - FreePlanCantHaveCompatiblePackageGroupError - SubscriptionMustHaveSinglePlanError - AddonIsCompatibleWithPlan - AddonIsCompatibleWithGroup - DuplicateAddonProvisionedError - ScheduledMigrationAlreadyExistsError - SubscriptionAlreadyOnLatestPlan - EntityIdDifferentFromRefIdError - UnsupportedFeatureType - UnsupportedVendorIdentifier - UnsupportedSubscriptionScheduleType - InvalidEntitlementResetPeriod - IncompatibleSubscriptionAddon - UnPublishedPackage - MeteringNotAvailableForFeatureType - AuthCustomerMismatch - AuthCustomerReadonly - FetchAllCountriesPricesNotAllowed - MemberInvitationError - PlansCircularDependencyError - NoFeatureEntitlementInSubscription - CheckoutIsNotSupported - UnsupportedParameter - PricingModelNotSupportedByBillingIntegration - BillingIntegrationMissing - BillingIntegrationAlreadyExistsError - InvalidMemberDelete - PackageAlreadyPublished - DraftPlanCantBeArchived - DraftAddonCantBeArchived - PlanWithChildCantBeDeleted - PlanCannotBePublishWhenBasePlanIsDraft - PlanCannotBePublishWhenCompatibleAddonIsDraft - PlanIsUsedAsDefaultStartPlan - PlanIsUsedAsDowngradePlan - InvalidAddressError - InvalidQuantity - BillingPeriodMissingError - DowngradeBillingPeriodNotSupportedError - CustomerAlreadyUsesCouponError - CustomerAlreadyHaveCustomerCoupon - SubscriptionAlreadyCanceledOrExpired - TrialMustBeCancelledImmediately - SubscriptionDoesNotHaveBillingPeriod - InvalidCancellationDate - FailedToImportCustomer - FailedToImportSubscriptions - PackagePricingTypeNotSet - InvalidSubscriptionStatus - InvalidArgumentError - EditAllowedOnDraftPackageOnlyError - ResyncAlreadyInProgress - ArchivedCouponCantBeApplied - ImportAlreadyInProgress - AddonHasToHavePriceError - SelectedBillingModelDoesntMatchImportedItemError - CannotArchiveProductError - CannotUnarchiveProductError - CannotDeleteCustomerError - CannotRemovePaymentMethodFromCustomerError - CannotDeleteFeatureError - CannotArchiveFeatureError - InvalidUpdatePriceUnitAmountError - ExperimentAlreadyRunning - ExperimentStatusError - OperationNotAllowedDuringInProgressExperiment - EntitlementsMustBelongToSamePackage - CanNotUpdateEntitlementsFeatureGroup - MeterMustBeAssociatedToMeteredFeature - CannotEditPackageInNonDraftMode - CannotAddOverrideEntitlementToPlan - MissingEntityIdError - NoProductsAvailable - PromotionCodeNotForCustomer - PromotionCodeNotActive - PromotionCodeMaxRedemptionsReached - PromotionCodeMinimumAmountNotReached - PromotionCodeCustomerNotFirstPurchase - AddonWithDraftCannotBeDeletedError - CannotReportUsageForEntitlementWithMeterError - RecalculateEntitlementsError - ImportSubscriptionsBulkError - InvalidMetadataError - CannotUpsertToPackageThatHasDraft - IntegrationValidationError - AwsMarketplaceIntegrationValidationError - AwsMarketplaceIntegrationError - DataExportIntegrationError - HubspotIntegrationError - DuplicateProductValidationError - AmountTooLarge - CustomerHasNoEmailAddress - MergeEnvironmentValidationError - EntitlementLimitExceededError - EntitlementUsageOutOfRangeError - UsageMeasurementDiffOutOfRangeError - AddonQuantityExceedsLimitError - AddonDependencyMissingError - PackageGroupMinItemsError - CannotUpdateUnitTransformationError - SingleSubscriptionCantBeAutoCancellationTargetError - MultiSubscriptionCantBeAutoCancellationSourceError - ChangingPayingCustomerIsNotSupportedError - RequiredSsoAuthenticationError - InvalidDoggoSignatureError - InvalidReceivedSignatureError - CannotDeleteDefaultIntegration - CannotChangeBillingIntegration - FailedToResolveBillingIntegration - WorkflowTriggerNotFound - DeprecatedEstimateSubscriptionError - FeatureConfigurationExceededLimitError - FeatureNotBelongToFeatureGroupError - FeatureGroupMissingFeaturesError - VersionExceedsMaxValueError - CannotUpdateExpireAtForExpiredCreditGrantError - ExpireAtMustBeLaterThanEffectiveAtError - OfferAlreadyExists - DraftAlreadyExists - CreditGrantAlreadyVoided - CreditGrantCannotBeVoided - InvalidTaxId - ObjectAlreadyBeingUsedByAnotherRequestError - TooManySubscriptionsPerCustomer - TooManyCustomCurrencies - StripeError - SchedulingAtEndOfBillingPeriod - ApiKeyExpired - ApiKeyHasExpiry nullable: true required: - message - code UnauthenticatedErrorResponseDto: type: object properties: message: type: string code: type: string enum: - Unauthenticated nullable: true required: - message - code ForbiddenErrorResponseDto: type: object properties: message: type: string code: type: string enum: - IdentityForbidden - AccessDeniedError - NoFeatureEntitlementError nullable: true required: - message - code TooManyRequestsErrorResponseDto: type: object properties: message: type: string code: type: string enum: - RateLimitExceeded nullable: true required: - message - code securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY description: Server API Key ````