Announcing our new Vercel integration
Join our Discord
Sign up for free

via HTTP

You can send us events with a single POST request to$ingestKey, or with the key as a Bearer token. The request body must be your JSON-encoded event and has a maximum size of 256KB. On success, the API returns a 201 status code. This can be done via your API or used as a webhook.

Our ingestion API allows you to perform a single POST request to submit an event from your application code or webhook. For convenience, we offer pre-built libraries for making this POST request in several popular languages, but in essence — it's a POST request!

HTTP requests

You can send us events by making a single HTTP POST request to$ingestKey, swapping $ingestKey for an ingest key from your dashboard.

The body must be your JSON-encoded event payload in the format described in our event documentation, and can currently be no larger than 256KB. If you need to increase your payload limit contact us.

curl -X POST '' \
-d '{"name": "test.event", "data": { "favorites": ["milk", "tea", "eggs"] } }'

HTTP Responses

The API server returns status codes to indicate the status of the request:

  • 201: The event was successfully ingested
  • 400: The request was malformed
  • 401: The ingest key was not found
  • 403: The event does not match the ingest key filter
  • 413: The event is greater than your limit (currently 256KB)

HTTP Authentication

Your keys for authenticating with the event ingestion API are visible within the dashboard (in Events → Sources). By default, each workspace has a single ingestion key which can send any event from any IP.

You can create new ingest keys at any time, and you can have up to 100 ingest keys in a workspace.

Filtering: allowlists and denylists

When creating ingest keys you can add an optional filter. A filter is either an allowlist or a denylist:


allowlist allows you to specify the events that the key can fire, and which IPs can use the key. If other events or IPs attempt to use the key, the API returns with a 403 status code.


denylist allows you to specify events which the key cannot fire, or IPs which cannot use the key. If the key is used to attempt these events the API returns with a 403 status code.


We recommend always using a filter for public-facing ingest keys. This ensures that public keys, like the keys you use on your website, can only send specific events that are not relevant to your internal processes.

If you'd prefer to send your ingest key in the request header instead of having the key in the URL, you can:

  • Send a POST request to the domain with no path.
  • Include the Authorization header with your key: Authorization: Bearer $KEY
  • The request body is your event payload