Events API

Ingest usage events into Meterd.

Ingest a single event

POST/v1/events

Request body

json

{
  "event_type": "api_request",
  "customer_id": "01HQXYZ...",
  "timestamp": "2024-01-15T10:30:00Z",
  "properties": {
    "endpoint": "/v1/users",
    "method": "GET",
    "region": "us-east-1"
  },
  "value": 1.0,
  "idempotency_key": "req_abc123"
}

Field	Type	Required	Description
`event_type`	string	Yes	Event category (must match a meter's event_type)
`customer_id`	string	Yes	Customer's external ID (auto-creates the customer if not found)
`timestamp`	ISO 8601	No	Event time (defaults to server time)
`properties`	object	No	Arbitrary key-value metadata
`value`	number	No	Numeric value (defaults to 1.0)
`idempotency_key`	string	No	Deduplication key

Response

json

{ "accepted": 1, "rejected": 0, "warnings": [] }

Field	Type	Description
`accepted`	number	Number of events accepted
`rejected`	number	Number of events rejected
`warnings`	string[]	Non-fatal issues (e.g., unrecognized event type)

Example

bash

curl -X POST https://api.meterd.io/v1/events \
  -H "Authorization: Bearer mtd_adm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "api_request",
    "customer_id": "01HQXYZ...",
    "properties": {"endpoint": "/users"},
    "idempotency_key": "req_001"
  }'

Ingest a batch of events

POST/v1/events/batch

Send up to 1,000 events in a single request for higher throughput.

json

{
  "events": [
    { "event_type": "api_request", "customer_id": "01HQXYZ...", "properties": {"endpoint": "/users"} },
    { "event_type": "api_request", "customer_id": "01HQABC...", "properties": {"endpoint": "/orders"} }
  ]
}

Response

json

{ "accepted": 2, "rejected": 0, "warnings": [] }

Idempotency

If you include an idempotency_key, Meterd deduplicates the event. Sending the same key twice means the second request is silently accepted (no error, no double-counting). Use when retrying after timeouts or when your upstream may emit duplicates.

Rate limiting

The events API is rate-limited to 1,000 requests per minute per tenant. The response includes X-RateLimit-Limit and X-RateLimit-Remaining headers so you can track your usage.

When rate-limited, the API returns 429 Too Many Requests with a Retry-After header.