Skip to main content
POST
/
usage
/
events
Python SDK
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",
    "amount": 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",
    "amount": 3,
    "credit_used": 10,
    "event_id": "evt_external_789",
    "timestamp": 1703246400000,
    "metadata": {
        "feature_type": "advanced",
        "user_tier": "premium"
    }
})

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

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.

Usage endpoints are served from https://api-meter.metrifox.com. Other API calls stay on 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"
}

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
customer_key
string
required

The unique customer identifier in your application

​
event_id
string
required

Required idempotency key for this event. Must be unique per event.

​
event_name
string | null

The name of the event as set up in the Metrifox platform. Either event_name or feature_key is required.

​
feature_key
string | null

Feature key associated with this usage event. Either event_name or feature_key is required.

​
quantity
number
default:1

The quantity of usage. Defaults to 1 if not provided

​
credit_used
integer | null

Optional credits used for this event

​
timestamp
integer | null

Unix timestamp (in milliseconds) when the event occurred. Defaults to current time if not provided. Supplying this improves ordering and debugging.

​
metadata
object

Optional metadata to attach to the event

Response

Usage recorded successfully

​
data
object
​
message
string
Example:

"Event received"