---
title: "Query governance access"
method: POST
path: "/openmeter/governance/query"
tags: ["OpenMeter Governance"]
---

# Query governance access

`POST /openmeter/governance/query`

Query feature access for a list of customers.

The endpoint resolves each provided identifier to a customer and returns the
access status for the requested features, plus optional credit balance
availability.

_Designed to be called on a fixed refresh interval and the query response is
intended to be cached._

## Query parameters

- `page` CursorPaginationQueryPage — Determines which page of the collection to retrieve.
  - `size` integer — The number of items to include per page.
  - `after` string — Request the next page of data, starting with the item after this parameter.
  - `before` string — Request the previous page of data, starting with the item before this parameter.

## Request body

- GovernanceQueryRequest — Query to evaluate feature access for a list of customers.
  - `include_credits` boolean — Whether to include credit balance availability for each resolved customer. When true, each feature evaluation includes credit balance checks. Defaults to `false`.
  - `customer` GovernanceQueryRequestCustomers, required — List of customer identifiers to evaluate access for.
    - `keys` string[], required — Each entry can be a customer `key` or a usage-attribution subject `key`. Identifiers that cannot be resolved to a customer are reported in the response `errors` array.
  - `feature` GovernanceQueryRequestFeatures — Optional list of feature keys to evaluate access for. If omitted, all features available in the organization are returned. Providing this list is recommended to reduce the response size and the load on the backend services.
    - `keys` string[], required — List of feature keys to evaluate access for.

## Response `200`

The request has succeeded.

- GovernanceQueryResponse — Response of the governance query.
  - `data` GovernanceQueryResult[], required — Access evaluation results, one entry per resolved customer.
    - `matched` string[], required — The list of identifiers from the request that resolved to this customer. Each entry is either the customer `key` or one of its usage-attribution subject `key`s. Duplicate or aliased identifiers that resolve to the same customer collapse to a single result entry, with every requested identifier listed here.
    - `customer` BillingCustomer, required — Customers can be individuals or organizations that can subscribe to plans and have access to features.
      - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier).
      - `name` string, required — Display name of the resource. Between 1 and 256 characters.
      - `description` string — Optional description of the resource. Maximum 1024 characters.
      - `labels` Labels — Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. Keys must be of length 1-63 characters, and cannot start with "kong", "konnect", "mesh", "kic", or "_".
      - `created_at` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.
      - `updated_at` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.
      - `deleted_at` string, date-time — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.
      - `key` string, required — ExternalResourceKey is a unique string that is used to identify a resource in an external system.
      - `usage_attribution` BillingCustomerUsageAttribution — Mapping to attribute metered usage to the customer. One customer can have zero or more subjects, but one subject can only belong to one customer.
        - `subject_keys` UsageAttributionSubjectKey[], required — The subjects that are attributed to the customer. Can be empty when no usage event subjects are associated with the customer.
      - `primary_email` string — The primary email address of the customer.
      - `currency` string — Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience.
      - `billing_address` Address — Address
        - `country` string — [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 country code. Custom two-letter country codes are also supported for convenience.
        - `postal_code` string — Postal code.
        - `state` string — State or province.
        - `city` string — City.
        - `line1` string — First line of the address.
        - `line2` string — Second line of the address.
        - `phone_number` string — Phone number.
    - `features` object, required — Map of features with their access status. Map keys are the feature keys requested in `feature.keys`, or every feature `key` available in the organization when the feature filter was omitted.
    - `updated_at` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.
  - `errors` GovernanceQueryError[], required — Partial errors encountered while processing the request.
    - `code` 'unknown' | 'customer_not_found', required — Error code for a governance query failure.
    - `message` string, required — Human-readable description of the error.
    - `attributes` object — Additional structured context.
    - `customer` string — The customer identifier from the request that produced this error.
  - `meta` CursorMeta, required — Pagination metadata.
    - `page` CursorMetaPage, required
      - `first` string, path — URI to the first page
      - `last` string, path — URI to the last page
      - `next` string, path, nullable, required — URI to the next page
      - `previous` string, path, nullable, required — URI to the previous page
      - `size` number, required — Requested page size

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden

---

[API](https://skmtc.net/openmeterio/apis/openmeter-and-konnect-metering-billing-api.md) · [All operations](https://skmtc.net/openmeterio/apis/openmeter-and-konnect-metering-billing-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openmeterio/openmeter-and-konnect-metering-billing-api/versions/9bca44e2d61d/schema)