Metering & Billing Policy

Metering & Billing requires a separate purchase. Contact Sales for pricing and availability.

The Metering & Billing Policy meters AI token usage for usage-based billing on AI Gateway traffic. The Policy supports flexible customer identification, custom pricing dimensions, and fine-grained traffic filtering.

Legacy built-in event ingestion: If you previously enabled metering using the built-in Konnect UI, do not enable the Metering & Billing Policy at the same time. This can result in duplicate events. Disable the built-in event ingestion first, then enable the Policy.

The Metering & Billing Policy runs in the AI Gateway request/response path and emits usage events in CloudEvents format. These events are immutable once emitted and aren’t observability or analytics signals.

For each request, the Policy:

1. Resolves the subject (the customer identity that gets billed) from the configured source (an AI Consumer, application, or request header).
2. Captures standard AI Gateway metadata on the event, including the AI Model, AI Agent, or AI MCP Server that handled the request, and the response status.
3. Attaches any configured custom attributes from request headers or query parameters, such as department, project, or priority tier.
4. Buffers the event locally and delivers it in batches to the configured ingest endpoint, with automatic retries on failure:
   • Konnect Metering & Billing ingest endpoint: https://us.api.konghq.com/v3/openmeter/events
   • OpenMeter self-hosted ingest endpoint: https://127.0.0.1/api/v3/openmeter/events

Events and subjects

Every usage event has a subject that identifies who is billed for the request. The subject is the most important configuration decision because it determines how usage is grouped and aggregated. You can set the subject to an AI Consumer, Konnect Dev Portal application, or any request header value such as x-customer-id or x-tenant-id.

If the Policy can’t resolve a subject from the configured source (for example, if the expected header is missing), the event is dropped.

Filtering traffic and custom dimensions

You can further narrow which traffic and dimensions the Policy will ingest as events. The following table describes how you can configure the Policy to filter traffic or custom dimensions:

Buffering and delivery

The Policy buffers events in a local queue before sending them to the ingest endpoint in batches. If delivery fails, the queue retries with exponential backoff up to the configured maximum retry duration. Events that can’t be delivered within that window are dropped. The Policy itself is stateless; it doesn’t persist events across restarts.

The Metering & Billing Policy only meters events, it doesn’t enforce metered limits. You must use a rate limiting policy alongside the Metering & Billing Policy to enforce limits.

For example, if you’re metering AI request tokens to 100 per month, you must use the AI Rate Limiting Advanced Policy to limit the tokens.

The Metering & Billing Policy can’t bill customers. If you want to bill customers based on usage events from the Policy, use Konnect Metering & Billing or OpenMeter self-hosted.

Meter AI token usage

Emit separate usage events for AI input and output tokens on AI Gateway requests, billed to the authenticated AI Consumer:

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/policies \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "metering-and-billing",
      "type": "metering-and-billing",
      "display_name": "AI metering",
      "config": {
        "ingest_endpoint": "https://us.api.konghq.com/v3/openmeter/events",
        "api_token": "your-api-token",
        "meter_api_requests": false,
        "meter_ai_token_usage": true,
        "subject": {
          "look_up_value_in": "consumer"
        }
      }
    }
    '

ai_gateway_policies:
  - ref: metering-and-billing
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    name: metering-and-billing
    type: metering-and-billing
    display_name: AI metering
    config:
      ingest_endpoint: https://us.api.konghq.com/v3/openmeter/events
      api_token: your-api-token
      meter_api_requests: false
      meter_ai_token_usage: true
      subject:
        look_up_value_in: consumer

Capture custom billing dimensions

Attach department and project dimensions from request headers to every usage event:

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/policies \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "metering-and-billing",
      "type": "metering-and-billing",
      "display_name": "AI metering",
      "config": {
        "ingest_endpoint": "https://us.api.konghq.com/v3/openmeter/events",
        "api_token": "your-api-token",
        "meter_api_requests": true,
        "meter_ai_token_usage": false,
        "subject": {
          "look_up_value_in": "consumer"
        },
        "attributes": [
          {
            "source": "header",
            "look_up_value_in": "x-department",
            "event_property_name": "department"
          },
          {
            "source": "header",
            "look_up_value_in": "x-project",
            "event_property_name": "project"
          }
        ]
      }
    }
    '

ai_gateway_policies:
  - ref: metering-and-billing
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    name: metering-and-billing
    type: metering-and-billing
    display_name: AI metering
    config:
      ingest_endpoint: https://us.api.konghq.com/v3/openmeter/events
      api_token: your-api-token
      meter_api_requests: true
      meter_ai_token_usage: false
      subject:
        look_up_value_in: consumer
      attributes:
      - source: header
        look_up_value_in: x-department
        event_property_name: department
      - source: header
        look_up_value_in: x-project
        event_property_name: project

These attributes are included in the event data payload and can be used to apply tiered pricing rules, enforce per-department usage budgets, or produce internal chargeback reports. If a header is absent on a given request, that attribute is omitted from that event.