Skip to content
IForevents Docs
IForevents Docs
InicioPanelGitHubPrivacidadTérminosSeguridadIntroducción
Referencia de la API
Queue up to 500 events POSTCreate or update a tracked user POSTRecord one event POST
Soporte y SLA
API ReferenceEndpointsIngest

Queue up to 500 events

POST
/v1/events/batch

Events are validated as a whole and accepted or refused as a whole. 202 means the whole batch is durably accepted (fsynced to the api's ingest log) and will reach analytics within about a second while ClickHouse is up; it does not mean the events are already queryable. 503 with Retry-After means nothing was accepted; retry the same batch. Items whose message_id was already accepted are answered as accepted and not stored again, so resending a batch is safe. All events of one batch belong to the user named by X-User-Id. Batching is the cheap path: one request for many events.

Authorization

projectKey
X-Project-Key<token>

Public write key. Safe to embed in client applications; grants ingest only. Paired with X-Project-Secret it also grants read-only programmatic access.

In: header

Header Parameters

X-User-Id?string

Who the event belongs to: your user id, or a per-visitor anonymous id you keep (the SDKs generate one). Same namespace as identify's custom_id. Omit only when a shared, address-derived profile is acceptable.

Length1 <= length <= 256

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/events/batch" \  -H "Content-Type: application/json" \  -d '{    "events": [      {        "created_at": "2026-09-13T12:30:45Z",        "name": "screen_view",        "properties": {          "screen": "home"        },        "type": "track"      },      {        "created_at": "2026-09-13T12:30:47Z",        "name": "button_tap",        "properties": {          "button": "buy"        },        "type": "track"      }    ]  }'
{  "status": "queued",  "user_uuid": "00000000-0000-0000-8b20-15635fadf462"}

A cohort's exact count and one page of members, most recently active first GET

Previous Page

Create or update a tracked user POST

Next Page

anonymous_id?string

The device's anonymous id (anon_...), kept after identify so destinations can merge the anonymous history. Forwarded to IForevents Cloud destinations; not stored.

context?

What the SDK knows about the device and app. Unknown members are dropped, strings are cut at 256 characters, and a context that does not decode is ignored. Forwarded to IForevents Cloud destinations; not stored.

events*array<>
message_id?string

The SDK's id for the call, a UUID made once per call and kept across retries (on a batch, each item carries its own). The api deduplicates on it for 24 hours: a resent call with the same id and content is answered as accepted and stored once; the same id with different content is refused with 409 event_id_conflict. Forwarded to IForevents Cloud destinations.

sent_at?string

When the SDK sent the request (RFC 3339), on the device's clock. Forwarded to IForevents Cloud destinations; not stored.