API reference

Events.

Events are the atomic unit of Flows. Every track call, every release marker, every error log, all land here. The shape is consistent across sources so one query pattern fits all.

The Event object

{
  "id": "evt_8F2qNc",
  "name": "signup_completed",
  "type": "track",
  "external_user_id": "u_1245",
  "session_id": "sess_Ab7K2",
  "props": { "plan": "pro", "referrer": "docs" },
  "timestamp": "2026-04-19T14:02:18.412Z",
  "project_id": "proj_7KfD1",
  "ingested_at": "2026-04-19T14:02:18.601Z"
}

Event types

track — user action (default). Feeds Flows funnel reports.
release — deployment marker. Created by the Releases API; do not post manually here.
error — error log event. Shown on user timeline, does not count toward funnel steps.

Ingest an event

POST/v0/eventsSingle event or batch

Single event:

curl -X POST https://api.brily.app/v0/events \
  -H "Authorization: Bearer $BRILY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "signup_completed",
    "external_user_id": "u_1245",
    "props": { "plan": "pro" },
    "timestamp": "2026-04-19T14:02:18Z"
  }'

Batch (up to 1 000 events per call). Same endpoint, array body:

curl -X POST https://api.brily.app/v0/events \
  -H "Authorization: Bearer $BRILY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "name": "checkout_started",
      "external_user_id": "u_1245",
      "timestamp": "2026-04-19T14:00:02Z"
    },
    {
      "name": "payment_error",
      "type": "error",
      "external_user_id": "u_1245",
      "props": { "code": "card_declined" },
      "timestamp": "2026-04-19T14:00:14Z"
    }
  ]'

Returns 202 Accepted with an ingest receipt. Events appear in flow reports within 60 seconds.

Browser widget

The Brily SDK exposes Brily.track() and reuses the same project / user identity as the NPS widget.

<script>
  window.Brily = window.Brily || {};
  Brily.init({
    project: "proj_7KfD1",
    user: { external_id: "u_1245" }
  });
</script>
<script src="https://cdn.brily.app/v1.js" defer></script>
<script>
  Brily.track("signup_completed", { plan: "pro" });
  Brily.track("checkout_started");
</script>

User timeline

GET/v0/users/{external_id}/timelineEvents for a single user, newest first

Query params: from, to, types (comma-separated), limit, cursor.

{
  "data": [
    {
      "id": "evt_8F2qNc",
      "name": "signup_completed",
      "type": "track",
      "timestamp": "2026-04-19T14:02:18Z",
      "props": { "plan": "pro" }
    },
    {
      "id": "evt_3aZk",
      "name": "signup_started",
      "type": "track",
      "timestamp": "2026-04-19T14:01:42Z"
    }
  ],
  "pagination": { "has_more": true, "next_cursor": "..." }
}

Retention

Raw events retained per pricing tier: 30 days on Pro, 90 days on Team and Agency. After retention, events roll up into events_hourly aggregates keyed by (flow_id, step, release_id) which continue to power funnel reports indefinitely.

Throughput

Per-project ingestion limit: 200 events per second sustained. Bursts up to 1 000 per second for 30 seconds. Exceeding returns 429 with a retry_after in the error body. Business and Enterprise plans get higher per-second caps on request.

Slack integration