/api/v1/eventsEvents 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
Only events with timestamp at or after this time.
Only events with timestamp before this time.
Only this event name.
Rows per page. Defaults to 100; at most 1,000.
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 "https://api.fictura.co/api/v1/events?after=2026-10-01T00:00:00Z&limit=1000" \
-H "Authorization: Bearer fk_data_..."Response
{
"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.
| Field | Meaning |
|---|---|
uuid | The row's id. Use it to de-duplicate when you re-read an overlapping range. |
external_id | sdk:<uuid> for an event sent with a uuid, the billing event's id for a webhook event. |
event, status, source | As sent to ingest; source is webhook on billing events. |
master_user_id | The person the event belongs to, the same id as Persons API. |
distinct_id | The sender's id: account id, else device id, else RevenueCat id, else master_user_id. |
account_id, device_id, revenuecat_id | The identifiers the event arrived with. |
session_id | The event's $session_id property. |
timestamp | When it happened, after clock-skew correction. |
inserted_at | When the row was written. |
properties | The event's properties, including $session_id and the SDK's context properties. |
platform, app_version, elements | Read from the properties ($os, $app_version, $elements). |
media_source, campaign, match_type | The person's first-touch attribution. |
product_id, currency, revenue_micros, period_type, environment | Billing 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.