Fictura
Data export
GET/api/v1/events

Events API

Page through an app's raw events from your own server, oldest first, with a cursor that never skips or repeats a row.

For a warehouse sync or a one-off pull. For whole date ranges as a file, use Bulk export; for a bucket kept up to date on a schedule, S3 destination.

Authorization

Authorization: Bearer fk_data_… with a key that has the events:read scope. Create one in Dashboard → Setup → Keys & webhook → Data API keys. The key names the app, so no app id is needed. The SDK key (gk_) is refused: it ships inside your app and must not read everyone's data. No key answers 401 missing_key, an unknown one 401 invalid_key, a key without the scope 403 missing_scope.

Query

after
string · ISO time or YYYY-MM-DD

Only events with timestamp at or after this time.

before
string · ISO time or YYYY-MM-DD

Only events with timestamp before this time.

event
string

Only this event name.

limit
number · 1 to 1000

Rows per page. Defaults to 100; at most 1,000.

cursor
string

The next_cursor from the previous page. Leave it off for the first page.

A bad value answers 400 with invalid_time, invalid_event, invalid_limit or invalid_cursor.

cURL
curl "https://api.fictura.co/api/v1/events?after=2026-10-01T00:00:00Z&limit=1000" \
  -H "Authorization: Bearer fk_data_..."

Response

200 — application/json
{
  "ok": true,
  "events": [
    {
      "uuid": "6f1c0b8e-6a8f-4f3e-9d1e-2c3b4a5d6e7f",
      "external_id": "sdk:3b2a…",
      "app_id": "6b8506b9-2f01-499b-a95a-e64ee67b2d3a",
      "event": "paywall_viewed",
      "status": "info",
      "source": "frontend",
      "master_user_id": "0f1e2d3c-4b5a-6978-8695-a4b3c2d1e0f9",
      "distinct_id": "8f14e45f",
      "account_id": "8f14e45f",
      "device_id": "ios-2c1d…",
      "revenuecat_id": null,
      "session_id": "0192…",
      "timestamp": "2026-10-01T09:14:03.120000Z",
      "inserted_at": "2026-10-01T09:14:04.512000Z",
      "properties": { "placement": "onboarding_end", "$session_id": "0192…" },
      "platform": "ios",
      "app_version": "2.0.68",
      "elements": null,
      "media_source": "tiktok",
      "campaign": "spring_drop",
      "match_type": "link_params",
      "product_id": null,
      "currency": null,
      "revenue_micros": null,
      "period_type": null,
      "environment": null
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0xMC0wMVQwOToxNDowMy4xMjBaIiwiaWQiOiI2ZjFjIn0",
  "has_more": true
}

Pages are ordered by (timestamp, uuid) and the cursor points just past the last row, so new events arriving while you page never shift a page you already read. On the last page next_cursor is null and has_more is false.

FieldMeaning
uuidThe row's id. Use it to de-duplicate when you re-read an overlapping range.
external_idsdk:<uuid> for an event sent with a uuid, the billing event's id for a webhook event.
event, status, sourceAs sent to ingest; source is webhook on billing events.
master_user_idThe person the event belongs to, the same id as Persons API.
distinct_idThe sender's id: account id, else device id, else RevenueCat id, else master_user_id.
account_id, device_id, revenuecat_idThe identifiers the event arrived with.
session_idThe event's $session_id property.
timestampWhen it happened, after clock-skew correction.
inserted_atWhen the row was written.
propertiesThe event's properties, including $session_id and the SDK's context properties.
platform, app_version, elementsRead from the properties ($os, $app_version, $elements).
media_source, campaign, match_typeThe person's first-touch attribution.
product_id, currency, revenue_micros, period_type, environmentBilling events only. revenue_micros is USD for store purchases; a Stripe sale's amount is in its currency.

Every key is always present: a field Fictura did not record for a row is null. Fields may be added over time, so write your loader to ignore keys it does not know.

Newer backends only

On a Fictura backend that predates this API, GET /api/v1/events answers 404.

On this page