---
title: "Ingest events"
method: POST
path: "/api/v1/events/ingest"
tags: ["Events"]
---

# Ingest events

`POST /api/v1/events/ingest`

Ingest usage events for metering and billing purposes.

Events are deduplicated by `(event_id, customer_id)` — re-sending the same pair will not be
double-counted. If timestamps differ across duplicates, the event with the latest timestamp is used.

By default, any invalid event rejects the entire batch. Set `allow_partial_failures` to `true` to ingest valid events and receive per-event failure details in the response body.

## Request body

- IngestEventsRequest
  - `allow_backfilling` boolean, nullable — Allow events with timestamps more than 1 day in the past. Defaults to `false`.
  - `allow_partial_failures` boolean, nullable — Accept the batch even if some events fail validation. Defaults to `false`. When `true`, valid events are ingested and failures are reported in the response body. When `false` (default), any invalid event rejects the entire batch.
  - `events` Event[], required — 1–100 events per request.
    - `code` string, required — Billable metric code. Max 512 characters.
    - `customer_id` string, required — Meteroid customer ID or external customer alias.
    - `event_id` string, required — Unique event identifier. Max 255 characters. A UUID or ULID is recommended.
    - `properties` object — Arbitrary string key-value pairs used by billable metrics for filtering and aggregation.
    - `timestamp` string, required — RFC 3339 timestamp. Defaults to ingestion time if omitted. Must be between 24 hours ago and 1 hour from now. Set `allow_backfilling` to remove the past limit.

## Response `200`

Events ingested successfully

- IngestEventsResponse
  - `failures` IngestFailure[] — Events that failed to ingest. Omitted when no failures.
    - `event_id` string, required
    - `reason` string, required

## Other responses

- `401` — Unauthorized
- `429` — Too many requests
- `500` — Internal error

## Changes

- **2026-04-28** (v1) `56373a72fa12` — 1 info
  - added the new optional request property `allow_partial_failures`
- **2026-03-27** (v1) `de35c02bb0d2` — 2 warning, 1 info
  - added the new `TOO_MANY_REQUESTS` enum value to the `code` response property for the response status `401`
  - added the new `TOO_MANY_REQUESTS` enum value to the `code` response property for the response status `500`
  - added the non-success response with the status `429`
- **2026-01-20** (v1) `665f680338b5` — 2 info
  - api tag `Events` added
  - api tag `events` removed
- **2025-10-14** (v1) `fd4347204b88` — 1 info
  - endpoint added
- **2025-07-09** (v1) `dece17f86f99` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/meteroid-oss/apis/meteroid/changes/api/v1/events/ingest/post.md)

---

[API](https://skmtc.dev/meteroid-oss/apis/meteroid.md) · [All operations](https://skmtc.dev/meteroid-oss/apis/meteroid/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/meteroid-oss/meteroid/revisions/03f9d8ae5c5e/schema)