Quickstart

Send your first event in under 5 minutes.

1. Sign up and get your API key

Create an account at app.meterd.io and navigate to Settings → API Keys to generate your first key.

Save the API key — it is only shown once. Export it along with your API base URL for the remaining steps:

bash

export METERD_URL="https://api.meterd.io"
export API_KEY="mtd_adm_..."

2. Create a meter

Define how events will be aggregated:

bash

curl -X POST $METERD_URL/v1/meters \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "api-requests",
    "event_type": "api_request",
    "aggregation": { "type": "count" },
    "window_size": "hour"
  }'

3. Create a customer (optional)

This step is optional — customers are created automatically when you send their first event.

bash

curl -X POST $METERD_URL/v1/customers \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "cust_123",
    "name": "Jane Doe"
  }'

4. Send an event

bash

curl -X POST $METERD_URL/v1/events \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "api_request",
    "customer_id": "cust_123",
    "properties": {
      "endpoint": "/v1/users",
      "method": "GET",
      "status": 200
    }
  }'

Note: customer_id in events is the customer's external ID string (e.g., cust_123), not the internal ULID.

5. Query usage

Wait a moment for aggregation, then query:

bash

curl "$METERD_URL/v1/usage?meter=api-requests&customer=cust_123" \
  -H "Authorization: Bearer $API_KEY"

6. Check a quota

Verify whether a customer still has capacity on a meter:

bash

curl -X POST $METERD_URL/v1/quota/check \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_123",
    "meter_slug": "api-requests",
    "requested": 1
  }'

The response includes allowed (boolean) and the current usage versus the quota limit.

Next steps

Read about authentication methods and API keys, understand core concepts, or explore the full API reference.