Skip to main content

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, the field 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.

Request Body required
    replace_existing_events boolean

    Default value: true

    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_start date-time required

    The (inclusive) start of the usage timeframe affected by this backfill.

    timeframe_end date-time required

    The (exclusive) end of the usage timeframe affected by this backfill.

    close_time 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_id string 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_id string 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_filter string nullable

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

Responses

OK

Response Headers
    Schema
      id string required
      status BackfillStatus required

      Possible values: [pending, reflected, pending_revert, reverted]

      The status of the backfill.

      created_at date-time required
      timeframe_start date-time required
      timeframe_end date-time required
      events_ingested integer required

      The number of events ingested in this backfill.

      close_time 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_at date-time nullable required

      The time at which this backfill was reverted.

      customer_id string 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_filter string nullable

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

    Loading...