Fictura
Events
POST/api/v1/events/log

Historical import

Send events that happened long ago, with their real times, through the normal ingest endpoint.

A normal batch to Ingest events is built for live traffic: each event's time is corrected for clock skew and then clamped to the last 48 hours, and the rate limits apply (6,000 events a minute per app, 600 per device). That is right for a phone and wrong for moving years of history out of another tool.

Set "historical": true on the batch to skip both:

  • Each event's timestamp is kept as sent, however old, instead of being clamped to 48 hours. A time in the future becomes now, and so does a missing or unreadable timestamp.
  • The per-app and per-device rate limits do not apply.

Everything else is the same: the 500-event batch cap, per-event validation, identity stitching and uuid de-duplication. Send a uuid on every event, so a batch you resend after a failure is not stored twice. One more difference: a historical batch is not mirrored to PostHog.

Server-side key only

historical is accepted only on a request that also carries a Data API key for the same app with the events:import scope (Authorization: Bearer fk_data_…), in addition to the app key. Anything else answers 403 historical_requires_import_key. The SDK key alone ships inside your app, and anyone holding it could otherwise backdate events into your reports.

The Data API keys panel does not offer this scope. Mint the key with a dashboard session and x-app-id: POST /api/v1/api-keys with {"name": "Backfill", "scopes": ["events:import"]}. The response's plaintext is the only time you see the key.

cURL
curl -X POST https://api.fictura.co/api/v1/events/log \
  -H "x-api-key: gk_..." \
  -H "Authorization: Bearer fk_data_..." \
  -H "x-account-id: 8f14e45f" \
  -H "Content-Type: application/json" \
  -d '{
    "historical": true,
    "events": [
      { "uuid": "2f6c…", "event_name": "subscription_started", "timestamp": "2024-03-02T10:00:00Z", "source": "backend" }
    ]
  }'

Send historical batches one after another rather than in parallel, and keep them to at most 500 events.

For RevenueCat or AppsFlyer history, use Dashboard → Setup → Import data instead: it brings the past in without any code.

Newer backends only

A Fictura backend that predates historical ignores the flag, so old timestamps are clamped to 48 hours. Check one imported event's time before sending a large backfill.

On this page