Tracking
How identify, track and batch fit together
Everything you send to IForevents is one of three calls, all authenticated with the public project key in the X-Project-Key header.
| Call | Endpoint | What it does |
|---|---|---|
| Track | POST /v1/events/track | Records one event for the user named in X-User-Id |
| Batch | POST /v1/events/batch | Queues up to 500 events in one request, all for one user |
| Identify | POST /v1/events/identify | Adds a name, e-mail and traits to a user's profile |
Users and events
Every track or batch request says who it is about in the X-User-Id header: your own id for the person (database id, username, e-mail) or an anonymous id you generate once per visitor and keep. Any string up to 256 characters. The profile is created the first time an id is seen, so nothing has to happen before the first event. identify takes the same value as custom_id and fills in the profile whenever you know more; events sent under the id before that already belong to it.
The SDKs do this for you: the browser SDK and the mobile SDKs generate an anonymous id (anon_...), keep it in local storage and send it on every request until identify replaces it with yours.
Requests without an id
An event with no X-User-Id is filed under a profile the api derives from the request's source address and User-Agent. That is a fallback, not an identity: everyone behind one corporate NAT, one mobile carrier, one proxy or one of your servers shares that profile, so unique users, funnels and retention count them as one person. Event counts stay right. Server-side integrations must always send X-User-Id; browser and mobile SDKs always do.
Events sent under an anonymous id are not merged into the profile a later identify names. If a visitor signs up mid-session, what they did before stays on the anonymous id.
Properties
Properties are a flat JSON object. Values are stored as strings, so 29.99 and "29.99" end up the same; keep keys stable across releases because the dashboard filters and segments by them.
Delivery
Ingest answers 201 as soon as the event is accepted and hands it to a queue. The dashboard shows it within a few seconds. Batches answer 202 while they are being processed.
Limits
Self-hosted installs have no event cap. On IForevents Cloud the Free plan includes 2,000,000 events per month and paid plans more; past the limit ingest keeps working for 7 days, then answers 429 with {"error":"quota_exceeded"} until the month rolls over or the plan is upgraded. See Billing.