HTTP ingest API

Use the ingest API when there's no Metrickle SDK for your platform, or to send events from your own servers, such as an order confirmed by your back end. The SDKs use this same endpoint, so events you send this way work in goals, funnels, journeys and protected flows like any other. Read Events, people and properties first for what to send.

Send a batch

POST https://in.metrickle.com/v1/batch

# Any other platform (server, game engine, desktop): POST batches of events
curl -X POST https://in.metrickle.com/v1/batch \
  -H "content-type: application/json" \
  -H "x-metrickle-key: mk_pub_YOUR_WRITE_KEY" \
  -d '{
    "sentAt": '$(date +%s000)',
    "context": { "library": { "name": "my-sdk", "version": "1.0" }, "platform": "ios",
                 "app": { "version": "2.3.0" }, "device": { "type": "mobile", "os": "iOS" } },
    "events": [{
      "id": "'$(uuidgen | tr A-Z a-z)'", "type": "screen", "name": "$screen", "ts": '$(date +%s000)',
      "anonymousId": "device-uuid", "sessionId": "session-uuid", "path": "Onboarding/Step1"
    }]
  }'

Send JSON with content-type: application/json. Put the app's write key (mk_pub_…, from the app's Settings page) in the x-metrickle-key header. If you can't set headers, for example with navigator.sendBeacon, put it in the body as writeKey instead.

A write key can only add events to its app, so it's safe to ship inside an app.

The batch

Context

When you leave out device, Metrickle reads the device type and operating system from the request's User-Agent.

Events

Send at most 256 KB per request.

Visitors and sessions

• Send the same anonymousId for every event from one device or install, and userId once the person has signed in. Metrickle then counts one person as one visitor across devices. See people and sessions.
• If you leave out anonymousId, Metrickle makes a visitor id from the request's IP address and user agent, which changes daily. From a server, every event would then look like the same visitor, so always send an id.
• If you leave out sessionId, a session is each 30-minute period of a visitor's activity.

Timestamps

Metrickle uses sentAt to correct for a sender whose clock is wrong. A time in the future is moved to the moment the batch arrived. A time more than 7 days in the past is moved to 7 days ago, so you can't use this API to import older history.

Revenue

Put a numeric revenue property on one of your own events. Send a refund as negative revenue with the same userId. See revenue.

Responses

Treat any 2xx, and any 4xx other than 429, as finished: sending the same batch again won't change the answer. After a 429, a 5xx or a network error, keep the events and try again with a growing delay, for example 1 second doubling up to a minute.

Requests are limited to about 600 a minute for each write key and sending address.

When a workspace is far over its plan's monthly events, Metrickle keeps a steady share of visitors and the response includes "sampled": true. See plans and billing.

Allowed origins and bots

• An app with allowed origins set accepts browser requests only from those domains and their subdomains. Requests without an Origin header, such as from a server or a native app, are always accepted.
• Batches with platform set to web are checked for crawlers and headless browsers by their User-Agent. They get a 202 but nothing is stored. Batches from other platforms aren't checked this way, so send server from your own back end.

What needs an SDK

The ingest API takes events you can describe yourself. Friction signals, accessibility settings, surveys, feedback, heatmaps and session replay come from the device, so they need a Metrickle SDK. See Web and React Native, iOS, Android or Flutter.