> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metrifox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get entitlements usage

> Retrieve entitlements usage breakdown for a subscription, including purchased, included, pay-as-you-go, and rollover pools



## OpenAPI

````yaml GET /api/v1/subscriptions/{subscription_id}/v2/entitlements-usage
openapi: 3.0.1
info:
  title: Metrifox API Documentation
  version: v1
  description: >-
    Welcome to Metrifox Platform's API documentation. This comprehensive API
    suite enables seamless integration with our platform, providing secure and
    efficient access to our services.
servers:
  - url: https://{defaultHost}
    variables:
      defaultHost:
        default: api.metrifox.com
security:
  - api_key: []
paths:
  /api/v1/subscriptions/{subscription_id}/v2/entitlements-usage:
    get:
      tags:
        - Subscriptions
      summary: Get entitlements usage for a subscription
      description: >
        Retrieves the entitlements usage breakdown for a specific subscription.
        Returns detailed pool information for each entitlement including
        purchased, included, pay-as-you-go, and rollover pools.


        Each entitlement includes:

        - **purchased_pool**: Usage purchased as part of the subscription

        - **included_pool**: Usage included in the plan at no extra cost

        - **pay_as_you_go_pool**: Usage billed on a pay-as-you-go basis

        - **rollover_quantity_pool**: Usage carried over from previous billing
        periods


        Pool balances show the remaining balance, amount used, and total
        allocated amount.
      operationId: getSubscriptionEntitlementsUsage
      parameters:
        - name: subscription_id
          in: path
          required: true
          description: The unique subscription identifier (UUID)
          schema:
            type: string
            format: uuid
          example: 625f5cee-259b-4994-b7eb-416b9e551f2c
      responses:
        '200':
          description: Entitlements usage fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitlementUsageResponse'
              examples:
                entitlements_usage:
                  summary: Entitlements Usage Response
                  value:
                    statusCode: 200
                    message: Entitlements usage fetched successfully
                    meta: {}
                    data:
                      - id: 120007eb-c6f7-4439-b7a9-75f09d60079e
                        feature_key: feature_skills_audit
                        type: per_use
                        included_pool: null
                        purchased_pool:
                          balance: '2.0'
                          used: '0.0'
                          amount: '2.0'
                          next_reset_at: '2026-03-12T16:55:21.847Z'
                          active: true
                        pay_as_you_go_pool: null
                        rollover_quantity_pool:
                          balance: '4.0'
                          used: '0.0'
                          amount: '4.0'
                          active: true
                        active: true
                        feature_name: Skills Audit
                      - id: 2e7f7fd8-c723-4d7c-98e5-b8239ab5226e
                        feature_key: feature_seats
                        type: persistent_use
                        included_pool: null
                        purchased_pool:
                          balance: '0.0'
                          used: '3.0'
                          amount: '3.0'
                          next_reset_at: '2026-03-12T16:55:21.847Z'
                          active: true
                        pay_as_you_go_pool: null
                        rollover_quantity_pool: null
                        active: true
                        feature_name: Seats
                    errors: {}
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Subscription not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 404
                message: Subscription not found
                errors:
                  subscription_id:
                    - >-
                      Subscription with ID
                      '625f5cee-259b-4994-b7eb-416b9e551f2c' does not exist
      x-codeSamples:
        - lang: python
          label: Python SDK
          source: >
            from metrifox_sdk import MetrifoxClient


            client = MetrifoxClient(api_key="your_api_key")


            # Get entitlements usage for a subscription

            subscription_id = "625f5cee-259b-4994-b7eb-416b9e551f2c"

            response =
            client.subscriptions.get_entitlements_usage(subscription_id)


            for entitlement in response['data']:
                print(f"Feature: {entitlement['feature_name']} ({entitlement['feature_key']})")
                print(f"  Type: {entitlement['type']}")
                print(f"  Active: {entitlement['active']}")
                if entitlement['purchased_pool']:
                    pool = entitlement['purchased_pool']
                    print(f"  Purchased: {pool['used']}/{pool['amount']} used, {pool['balance']} remaining")
                if entitlement['rollover_quantity_pool']:
                    pool = entitlement['rollover_quantity_pool']
                    print(f"  Rollover: {pool['used']}/{pool['amount']} used, {pool['balance']} remaining")
        - lang: javascript
          label: Javascript SDK
          source: >
            import { init } from "metrifox-js";


            const metrifoxClient = init({
              apiKey: process.env.METRIFOX_API_KEY
            });


            // Get entitlements usage for a subscription

            const subscriptionId = "625f5cee-259b-4994-b7eb-416b9e551f2c";

            const response = await
            metrifoxClient.subscriptions.getEntitlementsUsage(subscriptionId);


            response.data.forEach(entitlement => {
              console.log(`Feature: ${entitlement.feature_name} (${entitlement.feature_key})`);
              console.log(`  Type: ${entitlement.type}`);
              console.log(`  Active: ${entitlement.active}`);
              if (entitlement.purchased_pool) {
                const pool = entitlement.purchased_pool;
                console.log(`  Purchased: ${pool.used}/${pool.amount} used, ${pool.balance} remaining`);
              }
              if (entitlement.rollover_quantity_pool) {
                const pool = entitlement.rollover_quantity_pool;
                console.log(`  Rollover: ${pool.used}/${pool.amount} used, ${pool.balance} remaining`);
              }
            });
        - lang: ruby
          label: Ruby SDK
          source: >
            require 'metrifox-sdk'


            # Initialize with configuration

            METRIFOX_SDK = MetrifoxSDK.init({ api_key: "your-api-key" })


            # Get entitlements usage for a subscription

            subscription_id = "625f5cee-259b-4994-b7eb-416b9e551f2c"

            response =
            METRIFOX_SDK.subscriptions.get_entitlements_usage(subscription_id)


            response['data'].each do |entitlement|
              puts "Feature: #{entitlement['feature_name']} (#{entitlement['feature_key']})"
              puts "  Type: #{entitlement['type']}"
              puts "  Active: #{entitlement['active']}"
              if entitlement['purchased_pool']
                pool = entitlement['purchased_pool']
                puts "  Purchased: #{pool['used']}/#{pool['amount']} used, #{pool['balance']} remaining"
              end
              if entitlement['rollover_quantity_pool']
                pool = entitlement['rollover_quantity_pool']
                puts "  Rollover: #{pool['used']}/#{pool['amount']} used, #{pool['balance']} remaining"
              end
            end
components:
  schemas:
    EntitlementUsageResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 200
        message:
          type: string
          example: Entitlements usage fetched successfully
        meta:
          type: object
          additionalProperties: true
          description: Additional metadata
        data:
          type: array
          items:
            $ref: '#/components/schemas/EntitlementUsage'
          description: Array of entitlement usage records
        errors:
          type: object
          additionalProperties: true
          description: Any errors that occurred
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
        errors:
          type: object
          additionalProperties: true
          description: Detailed error information
    EntitlementUsage:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique entitlement usage identifier
        feature_key:
          type: string
          description: Unique key for the feature
        type:
          type: string
          description: Type of entitlement usage (e.g., per_use, persistent_use)
        included_pool:
          allOf:
            - $ref: '#/components/schemas/EntitlementPool'
          nullable: true
          description: Pool of included usage (null if not applicable)
        purchased_pool:
          allOf:
            - $ref: '#/components/schemas/EntitlementPool'
          nullable: true
          description: Pool of purchased usage
        pay_as_you_go_pool:
          allOf:
            - $ref: '#/components/schemas/EntitlementPool'
          nullable: true
          description: Pool of pay-as-you-go usage (null if not applicable)
        rollover_quantity_pool:
          allOf:
            - $ref: '#/components/schemas/EntitlementPool'
          nullable: true
          description: >-
            Pool of rolled-over quantity from previous periods (null if not
            applicable)
        active:
          type: boolean
          description: Whether the entitlement is currently active
        feature_name:
          type: string
          description: Human-readable name of the feature
    EntitlementPool:
      type: object
      nullable: true
      properties:
        balance:
          type: string
          description: Remaining balance in the pool
        used:
          type: string
          description: Amount used from the pool
        amount:
          type: string
          description: Total amount allocated to the pool
        next_reset_at:
          type: string
          format: date-time
          nullable: true
          description: When the pool resets next (null for pools that don't reset)
        active:
          type: boolean
          description: Whether the pool is currently active
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

````