Ingest events

The ingest endpoint is the primary method for sending usage events to Metronome, serving as the foundation for all billing calculations in your usage-based pricing model. This high-throughput endpoint is designed for real-time streaming ingestion, supports backdating 34 days, and is built to handle mission-critical usage data with enterprise-grade reliability. Metronome supports 100,000 events per second without requiring pre-aggregation or rollups and can scale up from there. See Getting usage into Metronome to learn more about usage events.

Use this endpoint to:

Create a customer usage pipeline into Metronome that drives billable metrics, credit drawdown, and invoicing. Track customer behavior, resource consumption, and feature usage

What happens when you send events:

• Events are validated and processed in real-time
• Events are matched to customers using customer IDs or customer ingest aliases
• Events are matched to billable metrics and are immediately available for usage and spend calculations

Usage guidelines:

• Historical events can be backdated up to 34 days and will immediately impact live customer spend
• Duplicate events are automatically detected and ignored (34-day deduplication window)

Event structure:

Usage events are simple JSON objects designed for flexibility and ease of integration:

{
  "transaction_id": "2021-01-01T00:00:00Z_cluster42",
  "customer_id": "team@example.com",
  "event_type": "api_request",
  "timestamp": "2021-01-01T00:00:00Z",
  "properties": {
    "endpoint": "/v1/users",
    "method": "POST",
    "response_time_ms": 45,
    "region": "us-west-2"
  }
}

Transaction ID

The transaction_id serves as your idempotency key, ensuring events are processed exactly once. Metronome maintains a 34-day deduplication window - significantly longer than typical 12-hour windows - enabling robust backfill scenarios without duplicate billing.

• Best Practices:
  • Use UUIDs for one-time events: uuid4()
  • For heartbeat events, use deterministic IDs
  • Include enough context to avoid collisions across different event sources

Customer ID

Identifies which customer should be billed for this usage. Supports two identification methods:

• Metronome Customer ID: The UUID returned when creating a customer
• Ingest Alias: Your system’s identifier (email, account number, etc.)

Ingest aliases enable seamless integration without requiring ID mapping, and customers can have multiple aliases for flexibility.

Event Type:

Categorizes the event type for billable metric matching. Choose descriptive names that aligns with the product surface area.

Properties:

Flexible metadata also used to match billable metrics or to be used to serve as group keys to create multiple pricing dimensions or breakdown costs by novel properties for end customers or internal finance teams measuring underlying COGs.