Ingest API

POST https://ingest.datalyr.com/track accepts one event from your server. Use it when no Datalyr SDK fits your language or runtime.

https://ingest.datalyr.com/track

Ingest is a different host and a different credential from the /v1 API. This endpoint writes. It reads nothing back.

Before you start

You must have the write key from Settings → API. It starts with dk_, and it selects the workspace on its own.

Keep the write key on your server. Anyone holding it can write events into your workspace. Never ship it in a browser bundle or a mobile binary.

Request

Item	Value
Method	`POST`. Every other method returns `405`.
Path	`/track`
Body	One JSON object. One event per request.

Headers

Header	Required	Value
`X-API-Key`	One of the two	Your write key, `dk_…`
`Authorization`	One of the two	`Bearer dk_…`
`Content-Type`	No	`application/json`. Send it anyway, so a proxy does not rewrite the body.
`User-Agent`	No	Sets the transport `source` the event is stored under. See Source detection.

Send X-API-Key or Authorization, not both. X-API-Key wins when both arrive. The workspace comes from the key. Do not put a workspace ID in the body, because /track ignores it.

Body fields

Every field below sits at the top level of the JSON object, except where the name starts with properties..

Field	Type	Required	Behavior
`event` or `event_name`	string	Yes	The event name. Missing returns `400`.
`distinct_id`, `user_id`, `anonymous_id`, or `visitor_id`	string	Yes, at least one	Identity. See Identity. Each also accepts its camelCase spelling.
`event_id`	string	No	Your own idempotency key. See Duplicates. `eventId`, `messageId`, and `message_id` are accepted spellings.
`timestamp`	string or number	No	ISO 8601, epoch seconds, or epoch milliseconds. Defaults to receipt time.
`properties`	object	No	Your event properties. Defaults to `{}`.
`context`	object	No	Client metadata. `library` and `version` get defaults.
`context.session_id`	string	No	Without it, Datalyr generates one that rolls at each UTC hour.
`context.userAgent`	string	No	Overrides the `User-Agent` header for device detection.
`external_ids`	object	No	Extra platform IDs. An array is ignored, so send an object.
`ip`	string	No	The end user’s IP. Send `"0"` to record no IP at all.

Two rules catch most integrations. A timestamp before 2020-01-01 falls back to receipt time, and a timestamp in the future is clamped to now. Attribution belongs inside properties, so a top-level utm_source is dropped.

Attribution properties

These go in properties, and each one lands in its own column.

Property	Holds
`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`	Campaign tagging
`gclid`, `fbclid`, `ttclid`, `gbraid`, `wbraid`, `oppref`	Ad click IDs
`clickId` with `clickIdType`	One click ID, named by its type
`lyr`	The tracking-link tag. `install_referrer_url` is parsed for it as a fallback.
`value`, `revenue`, or `amount`	Revenue. A numeric string is accepted.
`currency`	ISO code. Datalyr uppercases it.
`referrer`, `url`	Page context

clickIdType accepts fbclid, gclid, ttclid, gbraid, wbraid, msclkid, li_fat_id, epik, twclid, dclid, sclid, oppref, rdt_cid, obclid, irclid, irclickid, and ko_click_id. Datalyr drops any other type.

Example

curl "https://ingest.datalyr.com/track" \
  --header "X-API-Key: dk_YOUR_WRITE_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "event": "purchase",
    "user_id": "user_123",
    "anonymous_id": "anon_9f2c4e10",
    "event_id": "order_1001",
    "timestamp": "2026-08-20T12:00:00.000Z",
    "properties": { "value": 99.99, "currency": "USD", "gclid": "Cj0KCQ" }
  }'

Batching

/track takes one event per request. There is no batch array on this endpoint, so {"events": [ ... ]} posted here returns 400. The Web SDK batches on its own transport, which carries the public workspace ID rather than a write key. Use the Web SDK for browser traffic, and one /track request per event from a server.

Duplicates

Send event_id on every request, and a retry cannot double-count.

Behavior	Detail
Scope	One workspace. The same ID in two workspaces is two events.
Window	7 days
Response to a repeat	`200` with `{"success": false, "error": "Duplicate event detected"}`
After a `400` or a `500`	Retrying the same `event_id` is accepted, because the claim is released.

Branch on the success field, not on the status code. A duplicate is a 200.

Source detection

Datalyr reads the User-Agent header to record which transport the event arrived on.

`User-Agent` contains	Stored `source`
`@datalyr/react-native`, `@datalyr/swift`, `datalyr-ios`, `datalyr-android`	`mobile_app`
`@datalyr/api`, `datalyr-node`, `datalyr-python`, `datalyr-ruby`, `datalyr-go`, `datalyr-java`, `datalyr-php`	`api`
`mozilla`, `chrome`, `safari`, `firefox`, `edge`, `opera`	`browser`
Anything else, or no header	`api`

Geo columns and device fingerprints are recorded for mobile_app events. An api event carries the ip you send, and no geo.

Responses

A 200 with "success": true means Datalyr accepted the event and queued it.

{ "success": true, "event": "purchase", "workspace": "ws_public_id" }

Status	Body	Cause	Fix
`200`	`{"success":true,…}`	Accepted.	None.
`200`	`{"success":false,"error":"Duplicate event detected","event_id":"…"}`	This `event_id` arrived inside the last 7 days.	None. The first send counted.
`400`	`{"error":"Request body is required"}`	The request carried no body.	Send the JSON object.
`400`	`{"error":"Invalid JSON in request body"}`	The body did not parse to a JSON object.	Fix the JSON.
`400`	`{"error":"Event name is required (event or event_name field)"}`	No event name, or you posted an `events` array.	Send `event`. Send one event.
`400`	`{"error":"Identity required: provide distinct_id, user_id, anonymous_id, or visitor_id"}`	The body carried no identity field.	Send at least one of the four.
`401`	`{"error":"Missing API key. Please provide X-API-Key header or Authorization Bearer token."}`	No credential header.	Send `X-API-Key`.
`401`	`{"error":"Invalid API key"}`	The key is unknown, over 256 characters, or the workspace is inactive.	Copy the write key again from Settings → API.
`405`	`{"error":"Method not allowed"}`	You sent `GET`, `PUT`, or `DELETE`.	Use `POST`.
`413`	`{"error":"Payload too large. Maximum size is 256KB."}`	The body passed 256,000 bytes.	Trim `properties`. Split the work across events.
`429`	`{"error":"Rate limit exceeded. Maximum 1000 requests per second."}`	This key passed 1000 requests in one second.	Wait for `Retry-After`, which is `1`. Then retry.
`500`	`{"error":"Failed to enqueue event","details":"…"}`	Datalyr could not queue the event.	Retry with the same `event_id`.
`500`	`{"error":"Internal server error","error_id":"…"}`	A handler threw. The `X-Error-Id` header repeats the ID.	Retry once. Send `error_id` to support if it repeats.

Limits

Limit	Value
Request body	256,000 bytes
Requests per write key per second	1000
Events per request	1
API key length	256 characters
Duplicate window	7 days

CORS

/track answers OPTIONS with 204 and Access-Control-Allow-Origin: *. It allows Content-Type, X-API-Key, and Authorization. It sets no Access-Control-Allow-Credentials, so a browser request with credentials: 'include' fails. This endpoint is built for server calls.

Verify

Run the curl example above with your own write key.
Confirm the response reads "success": true.
Open Events in Datalyr.
Confirm a purchase row arrives within 30 seconds.

When it doesn’t work

Symptom	Cause	Fix
`401` on a key that works elsewhere	You sent the `dk_agent_` key.	Send the `dk_` write key. Ingest takes no Agent key.
`200` but no row in Events	The response read `"success": false`.	Read the `error` field. A duplicate `event_id` is the usual cause.
The event arrives with no campaign	You put `utm_source` at the top level.	Move every UTM and click ID inside `properties`.
Two rows for one order	You sent no `event_id`, then retried.	Send a stable `event_id` on every request.
The event lands hours off	Your `timestamp` did not parse.	Send ISO 8601, epoch seconds, or epoch milliseconds.

Node.js SDK: the same contract, with retries handled for you.
Errors and limits: the /v1 limits alongside these.
Agent access: what an agent can read once events land.

Agents and MCP

API Reference

Analytics

Events and users

Attribution and revenue

Cohorts and funnels

Metrics

Workspace

Conversion rules

Trackable links

Exports

Before you start

Request

Headers

Body fields

Attribution properties

Example

Batching

Duplicates

Source detection

Responses

Limits

CORS

Verify

When it doesn’t work

Next

​Before you start

​Request

​Headers

​Body fields

​Attribution properties

​Example

​Batching

​Duplicates

​Source detection

​Responses

​Limits

​CORS

​Verify

​When it doesn’t work

​Next

Before you start

Request

Headers

Body fields

Attribution properties

Example

Batching

Duplicates

Source detection

Responses

Limits

CORS

Verify

When it doesn’t work

Next