---
title: "Create backfill"
method: POST
path: "/events/backfills"
tags: ["Event"]
---

# Create backfill

`POST /events/backfills`

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](/api-reference/event/ingest-events) usage events, referencing the backfill (query parameter `backfill_id`).
3. [Close](close-backfill) 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](/extensibility/advanced-metrics#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.

## Request body

- NewBackfill
  - `replace_existing_events` boolean — 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` string, 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_end` string, 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_time` string, 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](/extensibility/advanced-metrics#computed-properties) used to filter the set of events to deprecate

## Response `200`

OK

- Backfill — A backfill represents an update to historical usage data, adding or replacing events in a timeframe.
  - `id` string, required
  - `status` 'pending' | 'reflected' | 'pending_revert' | 'reverted', required — The status of the backfill.
  - `created_at` string, date-time, required
  - `timeframe_start` string, date-time, required
  - `timeframe_end` string, date-time, required
  - `events_ingested` integer, required — The number of events ingested in this backfill.
  - `close_time` string, 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` string, 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](/extensibility/advanced-metrics#computed-properties) used to filter the set of events to deprecate
  - `replace_existing_events` boolean, 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.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `409` — Conflict
- `413` — Content Too Large
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.dev/orbcorp/apis/api-reference.md) · [All operations](https://skmtc.dev/orbcorp/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/orbcorp/api-reference/revisions/2580a0ee8d4c/schema)