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

# Record a Usage Event

> Records a usage event for a specific customer and feature. This endpoint is used to track feature usage for billing and quota management purposes.

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

**Important Notes**:

* `event_id` (required) is required for idempotency: You generate a unique UUID per real event. This prevents duplicates if sent multiple times. Metrifox will always send back a 200 response if the event is consumable but will record it only once per event\_id.
* `feature_key` (this is required if there is no event\_name): The unique key of the metered feature (from dashboard).
* `event_name` (optional if feature\_key is already provided): One of the event names configured on the feature (e.g., "api\_request" or "image\_generated")
* Include a `timestamp` (ms) when possible to aid ordering/debugging.

**Example response**:

```
{
  "data": {
    "customer_key": "cust-mit7k5v8obzs",
    "quantity": 1,
    "feature_key": "feature_job_posts"
  },
  "message": "Event received"
}
```


## OpenAPI

````yaml POST /usage/events
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/events:
    servers:
      - url: https://api-meter.metrifox.com
    post:
      tags:
        - Usage
      summary: Record usage event
      description: >-
        Records a usage event for a specific customer and feature. This endpoint
        is used to track feature usage for billing and quota management
        purposes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_key:
                  type: string
                  description: The unique customer identifier in your application
                event_name:
                  type: string
                  nullable: true
                  description: >-
                    The name of the event as set up in the Metrifox platform.
                    Either event_name or feature_key is required.
                feature_key:
                  type: string
                  nullable: true
                  description: >-
                    Feature key associated with this usage event. Either
                    event_name or feature_key is required.
                quantity:
                  type: number
                  description: The quantity of usage. Defaults to 1 if not provided
                  default: 1
                credit_used:
                  type: integer
                  nullable: true
                  description: Optional credits used for this event
                event_id:
                  type: string
                  description: >-
                    Required idempotency key for this event. Must be unique per
                    event.
                timestamp:
                  type: integer
                  nullable: true
                  description: >-
                    Unix timestamp (in milliseconds) when the event occurred.
                    Defaults to current time if not provided. Supplying this
                    improves ordering and debugging.
                metadata:
                  type: object
                  additionalProperties: true
                  description: Optional metadata to attach to the event
                  default: {}
              required:
                - customer_key
                - event_id
            examples:
              record_feature_usage:
                summary: Record Feature Usage
                value:
                  customer_key: cust-6d11ca90
                  event_name: candidate.sourced
                  quantity: 2
                  event_id: evt_12345
                  timestamp: 1703073600000
                  metadata:
                    source: linkedin
                    job_title: Software Engineer
              record_api_call:
                summary: Record API Call Usage
                value:
                  customer_key: cust-abc123
                  event_name: api.calls
                  quantity: 1
                  event_id: evt_api_123
                  credit_used: 5
                  timestamp: 1703073600500
                  metadata:
                    endpoint: /api/v1/search
                    response_time: 245
              record_storage_usage:
                summary: Record Storage Usage
                value:
                  customer_key: cust-xyz789
                  event_name: storage.gb
                  quantity: 0.5
                  event_id: evt_storage_456
                  timestamp: 1703160000000
                  metadata:
                    file_type: document
                    compression: gzip
              record_with_feature_key_only:
                summary: Record Usage with Feature Key Only
                value:
                  customer_key: cust-full123
                  feature_key: feature_job_posts
                  quantity: 3
                  event_id: evt_external_789
                  timestamp: 1703246400000
                  metadata:
                    feature_type: advanced
                    user_tier: premium
              record_with_all_fields:
                summary: Record with All Optional Fields
                value:
                  customer_key: cust-full123
                  event_name: premium.feature
                  quantity: 3
                  credit_used: 10
                  event_id: evt_external_789
                  timestamp: 1703246400000
                  metadata:
                    feature_type: advanced
                    user_tier: premium
      responses:
        '200':
          description: Usage recorded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      customer_key:
                        type: string
                        description: The customer key for which usage was recorded
                      quantity:
                        type: number
                        description: The quantity recorded
                      feature_key:
                        type: string
                        description: Feature or event key recorded
                  message:
                    type: string
                    example: Event received
              examples:
                usage_recorded:
                  summary: Usage Recorded Response
                  value:
                    data:
                      customer_key: cust-mit7k5v8obzs
                      quantity: 1
                      feature_key: feature_job_posts
                    message: Event received
        '400':
          description: Bad request - Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Validation failed
                errors:
                  customer_key:
                    - is required
                  event_name:
                    - either event_name or feature_key is required
                  event_id:
                    - is required
                  quantity:
                    - must be a positive number
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Unauthorized
        '404':
          description: Customer or event not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Customer not found
        '422':
          description: Unprocessable entity - Validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Validation failed
                errors:
                  quantity:
                    - must be greater than 0
      x-codeSamples:
        - lang: python
          label: Python SDK
          source: |
            from metrifox_sdk import MetrifoxClient
            import time

            client = MetrifoxClient(api_key="your_api_key")

            # Basic usage recording
            response = client.usages.record_usage({
                "customer_key": "cust-6d11ca90",
                "event_name": "candidate.sourced",
                "quantity": 2,
                "event_id": "evt_12345",  # required idempotency key
                "timestamp": int(time.time() * 1000)  # recommended
            })

            # Usage recording with all optional fields
            response = client.usages.record_usage({
                "customer_key": "cust-6d11ca90",
                "event_name": "premium.feature",
                "quantity": 3,
                "credit_used": 10,
                "event_id": "evt_external_789",
                "timestamp": 1703246400000,
                "metadata": {
                    "feature_type": "advanced",
                    "user_tier": "premium"
                }
            })
        - lang: javascript
          label: Javascript SDK
          source: |
            import { init } from "metrifox-js";

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

            // Basic usage recording
            await metrifoxClient.usages.recordUsage({
              customerKey: "cust-6d11ca90",
              eventName: "candidate.sourced",
              quantity: 2,
              eventId: "evt_12345", // required idempotency key
              timestamp: Date.now()  // recommended
            });

            // Usage recording with all optional fields
            await metrifoxClient.usages.recordUsage({
              customerKey: "cust-6d11ca90",
              eventName: "premium.feature",
              quantity: 3,
              creditUsed: 10,
              eventId: "evt_external_789",
              timestamp: 1703246400000,
              metadata: {
                feature_type: "advanced",
                user_tier: "premium"
              }
            });
        - lang: ruby
          label: Ruby SDK
          source: |
            require 'metrifox-sdk'

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

            # Basic usage recording
            response = METRIFOX_SDK.usages.record_usage({
              customer_key: "cust-6d11ca90",
              event_name: "candidate.sourced",
              quantity: 2,
              event_id: "evt_12345", # required idempotency key
              timestamp: (Time.now.to_f * 1000).to_i # recommended
            })

            # Usage recording with all optional fields
            response = METRIFOX_SDK.usages.record_usage({
              customer_key: "cust-6d11ca90",
              event_name: "premium.feature",
              quantity: 3,
              credit_used: 10,
              event_id: "evt_external_789",
              timestamp: 1703246400000,
              metadata: {
                feature_type: "advanced",
                user_tier: "premium"
              }
            })
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

````