Sign in

v49

latestOpenAPI 3.1.0raw.githubusercontent.com2026-07-081445491.8 MB
Event

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 deprecation_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.

You may not have multiple backfills in a pending or pending_revert state with overlapping timeframes.

post/events/backfills

Request body

replace_existing_eventsboolean

If true, replaces all existing events in the timeframe with the newly ingested events. If false, adds the newly ingested events to the existing events.

timeframe_startstring date-time required

The (inclusive) start of the usage timeframe affected by this backfill. By default, Orb allows backfills up to 31 days in duration at a time. Reach out to discuss extending this limit and your use case.

timeframe_endstring date-time required

The (exclusive) end of the usage timeframe affected by this backfill. By default, Orb allows backfills up to 31 days in duration at a time. Reach out to discuss extending this limit and your use case.

close_timestring date-time nullable

The time at which no more events will be accepted for this backfill. The backfill will automatically begin reflecting throughout Orb at the close time. If not specified, it will default to 1 day after the creation of the backfill.

customer_idstring nullable

The Orb-generated ID of the customer to which this backfill is scoped. Omitting this field will scope the backfill to all customers.

external_customer_idstring nullable

The external customer ID of the customer to which this backfill is scoped. Omitting this field will scope the backfill to all customers.

deprecation_filterstring nullable

A boolean computed property used to filter the set of events to deprecate

Example request

{
  "deprecation_filter": "my_numeric_property > 100 AND my_other_property = 'bar'"
}

Response

OK

idstring required
status'pending' | 'reflected' | 'pending_revert' | 'reverted' required

The status of the backfill.

created_atstring date-time required
timeframe_startstring date-time required
timeframe_endstring date-time required
events_ingestedinteger required

The number of events ingested in this backfill.

close_timestring date-time nullable required

If in the future, the time at which the backfill will automatically close. If in the past, the time at which the backfill was closed.

reverted_atstring date-time nullable required

The time at which this backfill was reverted.

customer_idstring nullable required

The Orb-generated ID of the customer to which this backfill is scoped. If null, this backfill is scoped to all customers.

deprecation_filterstring nullable

A boolean computed property used to filter the set of events to deprecate

replace_existing_eventsboolean required

If 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.

Example response

{
  "deprecation_filter": "my_numeric_property > 100 AND my_other_property = 'bar'"
}