Create backfill

Creating the backfill enables adding or replacing past events, even those that are older than the ingestion grace period. Performing a backfill in Orb involves 3 steps:

1. Create the backfill, specifying its parameters.
2. Ingest usage events, referencing the backfill (query parameter backfill_id).
3. Close the backfill, propagating the update in past usage throughout Orb.

Changes from a backfill are not reflected until the backfill is closed, so you won’t need to worry about your customers seeing partially updated usage data. Backfills are also reversible, so you’ll be able to revert a backfill if you’ve made a mistake.

This endpoint will return a backfill object, which contains an id. That id can then be used as the backfill_id query parameter to the event ingestion endpoint to associate ingested events with this backfill. The effects (e.g. updated usage graphs) of this backfill will not take place until the backfill is closed.

If the replace_existing_events is true, existing events in the backfill’s timeframe will be replaced with the newly ingested events associated with the backfill. If false, newly ingested events will be added to the existing events.

If a customer_id or external_customer_id is specified, the backfill will only affect events for that customer. If neither is specified, the backfill will affect all customers.

When replace_existing_events is true, this indicates that existing events in the timeframe should no longer be counted towards invoiced usage. In this scenario, the parameter filter can be optionally added which enables filtering using computed properties. The expressiveness of computed properties allows you to deprecate existing events based on both a period of time and specific property values.