Send events

POST https://pilotfox.app/api/v1/ingest/events

Records a batch of events. It needs an API key with ingest:write (see Server-side ingest for the key, the limits and how events are matched to visitors). Reference: POST /api/v1/ingest/events.

RequestCopy Anchor Link

A JSON object with one field, events: an array of 1 to 500 events, at most 1 MiB in all.

{
  "events": [
    { "site": "SITE_ID", "type": "event", "name": "subscription_renewed", "anonymous_id": "customer_8412" }
  ]
}

Each event has the fields of a browser event, plus four only the server can send (ip, user_agent, anonymous_id, ts), all optional. Like the browser's, events are read tolerantly: text that is too long is cut to its limit, a value PilotFox cannot use is dropped, and unknown fields are ignored, rather than refusing the event. The four server fields are the exception: a value of the wrong form refuses the event instead of being dropped, so an event is never filed under the wrong visitor or time. Only the problems listed under rejections refuse an event.

Event fieldsCopy Anchor Link

Which visitor an event belongs to depends on ip, user_agent and anonymous_id: see Matching server events to visitors.

Timestamps and late eventsCopy Anchor Link

ts lets you send events after the fact, for example from a queue or a retry: up to 7 days late. An event dated more than 30 minutes ago does not join the visitor's current session. It goes to a session of its own for that visitor and that 30-minute period, so a backlog sent twice lands in the same sessions, and it never shows in the realtime view.

PilotFox does not deduplicate events: a batch sent twice is stored twice. If a request fails without an answer (a network error, a timeout), you cannot tell whether its events were stored; decide whether a retry or a gap matters more to you.

ResponseCopy Anchor Link

200 with how many events were taken and which were rejected, by their position in events (counting from 0):

{
  "data": {
    "accepted": 2,
    "rejected": [
      { "index": 2, "code": "invalid" },
      { "index": 3, "code": "forbidden_site" },
      { "index": 4, "code": "ts_out_of_range" },
      { "index": 5, "code": "invalid" }
    ]
  }
}

A batch is not all-or-nothing: the events that pass are stored even when others are rejected. Check rejected on every answer.

accepted counts every event PilotFox took, including those it then drops on purpose: events excluded by the site's settings (an excluded IP address, network, country, path or user agent, or a hostname not on the allowed list) and, when the site blocks bots, events from a detected bot. The answer does not say which, as for the tracking script.

Rejected eventsCopy Anchor Link

Errors for the whole requestCopy Anchor Link

A complete exampleCopy Anchor Link

A subscription renews in your billing webhook, and you know the customer's user id; a second event is a purchase made during a request from the customer's browser, whose address and user agent your server saw.

curl -X POST "https://pilotfox.app/api/v1/ingest/events" \
  -H "Authorization: Bearer $PILOTFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{
  "events": [
    {
      "site": "SITE_ID",
      "type": "event",
      "name": "subscription_renewed",
      "anonymous_id": "customer_8412",
      "uid": "user_8412",
      "props": { "plan": "pro", "amount": 49, "annual": false },
      "ts": "2026-10-27T18:05:00+02:00"
    },
    {
      "site": "SITE_ID",
      "type": "event",
      "name": "order_paid",
      "url": "https://example.com/checkout",
      "ip": "203.0.113.7",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36",
      "uid": "user_8412",
      "props": { "order_id": "ord_5521", "total": 120 }
    }
  ]
}
EOF

{ "data": { "accepted": 2, "rejected": [] } }

To send many events, collect them and send up to 500 per request, at most 60 requests a minute per key.