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

Record one event

POST
/v1/events/track

Records a single event for the project identified by X-Project-Key. X-User-Id names the person: your own user id, or an anonymous id you generate and keep per visitor; the user exists by its events, no identify call needed (identify only adds a profile). Without the header the event is filed under a profile derived from the source address and User-Agent, which merges every caller behind one server, proxy or NAT into a single user. 201 means the event is durably accepted: written and fsynced to the api's ingest log, from which it reaches analytics within about a second while ClickHouse is up. It does not mean the event is already queryable. 503 with Retry-After means nothing was accepted; retry. A retry with the same message_id is stored once (docs/EVENT_IDENTITY.md).

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/track" \  -H "Content-Type: application/json" \  -d '{    "event_name": "checkout_completed",    "event_type": "track",    "properties": {      "items": 3,      "order_id": "ord_456",      "total": 99.99    }  }'
{  "status": "ok",  "user_uuid": "00000000-0000-0000-8b20-15635fadf462"}

Create or update a tracked user POST

Previous Page

Import another organization's export into this one (admin of both) 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.

created_at?string

When the event happened (RFC 3339), on your clock. Optional: absent means when the api received it. A time more than an hour ahead is replaced by the receive time. Part of the message_id fingerprint, so send the same value on a retry.

Formatdate-time
event_name*string

Event name, for example checkout_completed.

event_type?string

Defaults to track. page_view and screen are stored as page views; group and alias are not stored or counted as events and only reach the Cloud destinations, like identify.

Value in

  • "track"
  • "page_view"
  • "screen"
  • "group"
  • "alias"
group_id?string

Required when event_type is group: the account the user belongs to. properties are the account's traits.

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.

previous_id?string

Required when event_type is alias: the earlier id that X-User-Id now replaces.

properties?
sent_at?string

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