> ## 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.

# Check Access & Record

> Checks if a customer can use a feature and records the usage in one call. If access is granted the usage is recorded; if not, nothing happens.

> Usage endpoints are served from [https://api-meter.metrifox.com](https://api-meter.metrifox.com). Other API calls stay on [https://api.metrifox.com](https://api.metrifox.com).

For example, before a customer generates an AI image, check they have quota and record the
generation in a single call.

<Note>
  If the action doesn't complete — or the customer ends up using a different amount — correct the
  recorded usage with [Adjust a Usage Event](/api-reference/usage/adjust-usage).
</Note>


## OpenAPI

````yaml POST /usage/access
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:
  /usage/access:
    servers:
      - url: https://api-meter.metrifox.com
    post:
      tags:
        - Usage
      summary: Check access and record usage
      description: >-
        Checks if a customer can use a feature and records the usage in one
        call. If access is granted the usage is recorded; if not, nothing
        happens.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_key:
                  type: string
                  description: The unique customer identifier in your application.
                feature_key:
                  type: string
                  nullable: true
                  description: >-
                    Feature to check and record against. Either feature_key or
                    event_name is required.
                event_name:
                  type: string
                  nullable: true
                  description: >-
                    Event name configured on the feature. Either event_name or
                    feature_key is required.
                quantity:
                  type: number
                  default: 1
                  description: Quantity to check and record. Defaults to 1.
                event_id:
                  type: string
                  description: >-
                    Required idempotency key. The usage is recorded at most once
                    per event_id, so retries are safe.
                credit_used:
                  type: number
                  nullable: true
                  description: Optional credits used for this event (prepaid features).
              required:
                - customer_key
                - event_id
            examples:
              metered:
                summary: Check and record a metered feature
                value:
                  customer_key: cust-6d11ca90
                  feature_key: feature_interview_booking
                  quantity: 1
                  event_id: evt_chk_001
              prepaid:
                summary: Check and record a prepaid (credit) feature
                value:
                  customer_key: cust-6d11ca90
                  feature_key: feature_api_calls
                  quantity: 5
                  event_id: evt_chk_002
      responses:
        '200':
          description: Access checked. When can_access is true the usage was recorded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      customer_key:
                        type: string
                      feature_key:
                        type: string
                      requested_quantity:
                        type: number
                      can_access:
                        type: boolean
                        description: Whether access was granted (and therefore recorded).
                      recorded:
                        type: boolean
                        description: Whether the usage event was recorded.
                      unlimited:
                        type: boolean
                      balance:
                        type: number
                        description: Balance remaining after recording.
                      used_quantity:
                        type: number
                        description: Used quantity after recording.
                      entitlement_active:
                        type: boolean
                      prepaid:
                        type: boolean
                      wallet_balance:
                        type: number
                        description: Wallet balance after recording (prepaid features).
                      message:
                        type: string
              examples:
                granted_and_recorded:
                  summary: Access granted and usage recorded
                  value:
                    data:
                      customer_key: cust-6d11ca90
                      feature_key: feature_interview_booking
                      requested_quantity: 1
                      can_access: true
                      recorded: true
                      unlimited: false
                      balance: 3
                      used_quantity: 7
                      entitlement_active: true
                      prepaid: false
                      wallet_balance: 0
                      message: Feature found
                denied:
                  summary: Access denied, nothing recorded
                  value:
                    data:
                      customer_key: cust-6d11ca90
                      feature_key: feature_interview_booking
                      requested_quantity: 1
                      can_access: false
                      recorded: false
                      unlimited: false
                      balance: 0
                      used_quantity: 10
                      entitlement_active: true
                      prepaid: false
                      wallet_balance: 0
                      message: Insufficient balance
        '400':
          description: Bad request - Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Validation failed
                errors:
                  customer_key:
                    - is required
                  event_id:
                    - is required
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Unauthorized
        '404':
          description: Feature or customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Feature not found
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |
            curl -X POST "https://api-meter.metrifox.com/usage/access" \
              -H "x-api-key: your_api_key" \
              -H "Content-Type: application/json" \
              -d '{
                "customer_key": "cust-6d11ca90",
                "feature_key": "feature_interview_booking",
                "quantity": 1,
                "event_id": "evt_chk_001"
              }'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
        errors:
          type: object
          additionalProperties: true
          description: Detailed error information
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

````