Skip to main content

​
Send your first Event

This guide walks you through sending your first usage event to Monk.
What are events? Events record customer usage that gets aggregated by meters and charged on invoices. Learn more about events →

​
Prerequisites

​
Steps

​
1. Get Your API Key

  1. Navigate to Settings → API Keys in the Monk dashboard
  2. Copy your API key (looks like mk_live_...)
Settings page showing API Keys section
Keep your API key secret. Never expose it in client-side code.

​
2. Find Your Customer ID

You can use either:
  • Monk’s Customer ID: UUID from the dashboard or API response
  • Your External ID: The externalCustomerId you set when creating the customer

​
3. Send the Event

curl -X POST "https://events-api.monk.com/v1/events" \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "eventName": "call_count",
    "properties": {
      "endpoint": "/api/users"
    }
  }'

​
4. Verify

Check your event in the dashboard:
  1. Navigate to Usage-based → Events
  2. Find your event in the list
Usage events showing timestamp, event name, and customer

​
Using External Customer IDs

If you prefer your own identifiers: 
curl -X POST "https://events-api.monk.com/v1/events" \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalCustomerId": "cus_yourapp_123",
    "eventName": "call_count"
  }'

​
Sending Multiple Events

For bulk imports or high throughput, use the batch endpoint: 
curl -X POST "https://events-api.monk.com/v1/events/batch" \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "customerId": "cust-1", "eventName": "call_count" },
      { "customerId": "cust-2", "eventName": "call_count" }
    ]
  }'

​
Troubleshooting

​
”Customer not found”

  • Verify the customerId or externalCustomerId is correct
  • Check the customer exists in the Monk dashboard

​
”timestamp must not be more than 1 hour in the future”

  • The event’s timestamp is too far ahead of the server’s current time
  • Check for clock skew on the machine sending events
  • If timestamp is omitted, it defaults to now — this error only applies to explicitly set timestamps

​
”Event not appearing on invoice”

  • Customer needs an active contract
  • The contract’s plan must include a meter matching the eventName
  • Event timestamp must fall within the invoice’s billing period

​
Next Steps

Events Concepts

Learn about idempotency, infrastructure, and best practices

Events API

Full API specification

Batch Events

Send multiple events at once