> ## 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 All Usage Events

> Fetches a paginated list of usage events. Pagination is automatically applied even if no page parameters are provided.

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


## OpenAPI

````yaml GET /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
    get:
      tags:
        - Usage
      summary: Retrieves usage events
      description: >-
        Fetches a paginated list of usage events. Pagination is automatically
        applied even if no page parameters are provided.
      parameters:
        - name: page
          in: query
          required: false
          description: Page number (starts from 1)
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          required: false
          description: Number of records per page
          schema:
            type: integer
            default: 25
        - name: customer_key
          in: query
          required: false
          description: Filter events by customer key
          schema:
            type: string
        - name: event_name
          in: query
          required: false
          description: Filter events by event name (deprecated, use feature_key)
          schema:
            type: string
        - name: feature_key
          in: query
          required: false
          description: Filter events by feature key
          schema:
            type: string
      responses:
        '200':
          description: Events fetched
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        metadata:
                          type: object
                          additionalProperties: true
                          description: Additional metadata for the event
                        id:
                          type: string
                          description: Unique event identifier
                        credit_used:
                          type: integer
                          nullable: true
                          description: Number of credits used for this event
                        event_id:
                          type: string
                          description: External event identifier (idempotency key)
                        timestamp:
                          type: integer
                          description: >-
                            Unix timestamp in milliseconds when the event
                            occurred
                        event_name:
                          type: string
                          nullable: true
                          description: Name of the event (deprecated, use feature_key)
                        feature_key:
                          type: string
                          description: Feature key associated with this usage event
                        customer_key:
                          type: string
                          description: Unique customer identifier in your application
                        quantity:
                          type: number
                          description: Quantity of usage (can be positive or negative)
              examples:
                events_response:
                  summary: Usage Events Response
                  value:
                    data:
                      - metadata: {}
                        id: 92878f67-b956-4852-8b12-fde3c88fc94d
                        credit_used: null
                        event_id: 234567340178
                        timestamp: 1765306708000
                        event_name: null
                        feature_key: feature_job_posts
                        customer_key: cust-mit7k5v8obzs
                        quantity: 1
                      - metadata: {}
                        id: 9be6a05e-dbfa-4455-84f6-b5bb0cebd847
                        credit_used: null
                        event_id: 23456734012378
                        timestamp: 1765206678000
                        event_name: null
                        feature_key: feature_seats
                        customer_key: cust-mit7k5v8obzs
                        quantity: -1
                      - metadata: {}
                        id: 3fd7437d-6d6c-4c1c-a430-4da4f7d5aa71
                        credit_used: null
                        event_id: 23456785012378
                        timestamp: 1765206295000
                        event_name: null
                        feature_key: feature_payroll
                        customer_key: cust-mit7k5v8obzs
                        quantity: 1
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Unauthorized
      x-codeSamples:
        - lang: python
          label: Python SDK
          source: >
            from metrifox_sdk import MetrifoxClient


            client = MetrifoxClient(api_key="your_api_key")


            # List usage events with optional filters and pagination

            events = client.usages.list_events(
                customer_key="cust-6d11ca90",
                feature_key="feature_job_posts",
                page=1,
                per_page=25,
            )


            for event in events['data']:
                print(f"{event['feature_key']}: qty={event['quantity']} at {event['timestamp']}")

            print(f"Page {events['meta']['current_page']} of
            {events['meta']['total_pages']}")
        - lang: javascript
          label: Javascript SDK
          source: >
            import { init } from "metrifox-js";


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


            const events = await metrifoxClient.usages.listEvents({
              customerKey: "cust-6d11ca90",
              featureKey: "feature_job_posts",
              page: 1,
              perPage: 25,
            });


            events.data.forEach((e) => {
              console.log(`${e.feature_key}: qty=${e.quantity} at ${e.timestamp}`);
            });


            console.log(`Page ${events.meta.current_page} of
            ${events.meta.total_pages}`);
        - lang: ruby
          label: Ruby SDK
          source: |
            require 'metrifox-sdk'

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

            response = METRIFOX_SDK.usages.list_events(
              customer_key: "cust-6d11ca90",
              feature_key: "feature_job_posts",
              page: 1,
              per_page: 25
            )

            response["data"].each do |event|
              puts "#{event['feature_key']}: qty=#{event['quantity']} at #{event['timestamp']}"
            end
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

````