---
title: "Edit extract settings in bulk"
method: POST
path: "/api/v3/extracts/bulk-edit/"
tags: ["Extracts"]
---

# Edit extract settings in bulk

`POST /api/v3/extracts/bulk-edit/`

## Request

- Base URL: `https://embedded.improvado.io`
- URL: `https://embedded.improvado.io/api/v3/extracts/bulk-edit/`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `dts_session_id`
- TypeScript: <https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/docs/api/v3/extracts/bulk-edit/post.ts> (a function with typed inputs; its response is checked against the schema)

Change the settings of 1–1,000 accessible extractions of one data source and report type. Templates and data tables may differ. Only API extractions are supported: flat data, SQL, spreadsheet and file-import extractions are rejected. Requires extract UPDATE permission and an authenticated workspace user; service principals are not supported. Private connections must be owned by or shared with the caller.
Each setting is changed with the operations listed in ExtractionBulkEditRequest. A setting that is left out keeps each extraction's own value. Unknown settings or operations, an empty patch and conflicting operations return 400. Schedules and the historical date are checked like in the single-extract update, including the hourly scheduling entitlement and the agency's historical depth limit.
The request is accepted before the data source is consulted. The bulk edit then validates the settings each extraction ends up with in the data source and changes nothing if any of them is rejected, so it either changes every selected extraction or none. Poll the bulk status endpoint with the returned ID. Adding fields or changing additional_params, custom_filters or sync_historical_data re-downloads the history of active extractions; paused extractions stay paused.
An identical retry with the same Idempotency-Key returns the existing bulk edit ID; reusing the key with a different body returns 409. One bulk edit runs per agency at a time: a new bulk edit while another one is running returns 400.

## Headers

- `X-IM-WORKSPACE-ID` integer
- `Idempotency-Key` string, required

## Request body

- ExtractionBulkEditRequest: Supply at least one setting besides selection_params. Unknown keys return 400.
  - `selection_params` union, required: Select 1–1,000 accessible extractions by explicit IDs, or by a data-table filter. Non-empty select_ids takes precedence over filter_params and exclude_ids. In filter mode, exclude_ids are removed before checking count. Explicit IDs that are unavailable reject the entire request.
    - object
      - `select_ids` integer[], required: Internal extraction IDs, not the displayed extraction-order title or ID.
      - `exclude_ids` integer[]: IDs to exclude when using filter_params.
      - `count` integer: Optional expected resolved selection size; a mismatch returns 400.
      - `filter_params` object
        - `data_table_id` union, required: Data table ID.
          - string
          - integer
        - `status` string: UI statuses, comma-separated (syncing, data_synced, error, paused).
        - `query` string: Case-insensitive extraction title search.
    - object
      - `select_ids` integer[]: Internal extraction IDs, not the displayed extraction-order title or ID.
      - `exclude_ids` integer[]: IDs to exclude when using filter_params.
      - `count` integer: Optional expected resolved selection size; a mismatch returns 400.
      - `filter_params` object, required
        - `data_table_id` union, required: Data table ID.
          - string
          - integer
        - `status` string: UI statuses, comma-separated (syncing, data_synced, error, paused).
        - `query` string: Case-insensitive extraction title search.
  - `fields` object: Field names of the report type.
    - `replace` string[]
    - `add` string[]
    - `remove` string[]
  - `additional_params` BulkEditAdditionalParamsPatch: replace sets all params and cannot be combined with other operations. add sets a param only where it is missing, update sets it on every extraction, remove drops params by name. lookback_window, custom_refresh_window and sync_historical_data are not changed here. Set the lookback window through the lookback_window of scheduling, and the historical date through sync_historical_data.
    - `replace` object
    - `add` object
    - `update` object
    - `remove` string[]
  - `scheduling` BulkEditSchedulesPatch: replace sets the schedules on every extraction and cannot be combined with other operations. remove drops schedules equal to the given ones, add appends schedules an extraction does not have, and update then changes the given attributes of every remaining schedule. Changing timezone keeps the hours and minutes of each schedule.
    - `replace` ExtractionUpdateSchedule[]
      - `days` integer: Day offset within the interval, starting from 0. The valid range depends on `interval`: - `hour`, `day` — must be 0 - `week` — 0–6 (day of week) - `month` — 0–30 (day of month)
      - `hours` integer, required: Hour at which the run will start (0–23)
      - `minutes` integer, required: Minute of hour at which the run will start (0–59)
      - `interval` 'hour' | 'day' | 'week' | 'month': Frequency at which the run will be performed: - `hour` — every hour - `day` — once per day - `week` — once per week - `month` — once per month
      - `timezone` string: IANA timezone name (e.g. `UTC`, `America/New_York`) the schedule is interpreted in.
      - `recurrence` integer: How often the schedule repeats within the interval. Defaults to 1.
      - `lookback_window` object: Defines the period data will be extracted for. Applies to extract schedules only — ignored for load schedules.
        - `name` 'default' | 'live' | 'max': Lookback window preset: - `default` — past 30 days from the day of extract - `live` — past 1 day from the day of extract - `max` — past 60 days from the day of extract
    - `add` ExtractionUpdateSchedule[]
      - `days` integer: Day offset within the interval, starting from 0. The valid range depends on `interval`: - `hour`, `day` — must be 0 - `week` — 0–6 (day of week) - `month` — 0–30 (day of month)
      - `hours` integer, required: Hour at which the run will start (0–23)
      - `minutes` integer, required: Minute of hour at which the run will start (0–59)
      - `interval` 'hour' | 'day' | 'week' | 'month': Frequency at which the run will be performed: - `hour` — every hour - `day` — once per day - `week` — once per week - `month` — once per month
      - `timezone` string: IANA timezone name (e.g. `UTC`, `America/New_York`) the schedule is interpreted in.
      - `recurrence` integer: How often the schedule repeats within the interval. Defaults to 1.
      - `lookback_window` object: Defines the period data will be extracted for. Applies to extract schedules only — ignored for load schedules.
        - `name` 'default' | 'live' | 'max': Lookback window preset: - `default` — past 30 days from the day of extract - `live` — past 1 day from the day of extract - `max` — past 60 days from the day of extract
    - `remove` ExtractionUpdateSchedule[]
      - `days` integer: Day offset within the interval, starting from 0. The valid range depends on `interval`: - `hour`, `day` — must be 0 - `week` — 0–6 (day of week) - `month` — 0–30 (day of month)
      - `hours` integer, required: Hour at which the run will start (0–23)
      - `minutes` integer, required: Minute of hour at which the run will start (0–59)
      - `interval` 'hour' | 'day' | 'week' | 'month': Frequency at which the run will be performed: - `hour` — every hour - `day` — once per day - `week` — once per week - `month` — once per month
      - `timezone` string: IANA timezone name (e.g. `UTC`, `America/New_York`) the schedule is interpreted in.
      - `recurrence` integer: How often the schedule repeats within the interval. Defaults to 1.
      - `lookback_window` object: Defines the period data will be extracted for. Applies to extract schedules only — ignored for load schedules.
        - `name` 'default' | 'live' | 'max': Lookback window preset: - `default` — past 30 days from the day of extract - `live` — past 1 day from the day of extract - `max` — past 60 days from the day of extract
    - `update` object: Attributes to set on every schedule; omitted attributes keep each schedule's value.
      - `hours` integer
      - `minutes` integer
      - `timezone` string: IANA timezone name.
      - `interval` 'hour' | 'day' | 'week' | 'month'
      - `days` integer
      - `recurrence` integer
      - `lookback_window` object
  - `custom_filters` object: Source-side pre-filter. An empty string removes the filter.
    - `replace` string, required
  - `sync_historical_data` object
    - `replace` string, date, required: Must not be earlier than the agency's historical depth limit.
  - `hashed_fields` object: Names of fields whose values are hashed.
    - `replace` string[]
    - `add` string[]
    - `remove` string[]

## Response `200`

Bulk edit submitted or an identical previous submission returned. Does not mean the settings are already changed.

- BulkTaskSubmission
  - `id` string, uuid, required: Task ID to poll through GET /api/v3/bulk/stream/{task_info_id}/.

## Other responses

- `400`: Invalid request, missing or invalid key, empty selection, count mismatch, more than 1,000 extractions, a non-API extraction, mixed data sources or report types, an invalid patch, or another bulk edit of the agency is running.
- `401`: Authentication required.
- `403`: Insufficient permissions, inaccessible private connection, or unsupported service principal.
- `404`: One or more explicitly selected extractions are unavailable. The whole request is rejected.
- `409`: Idempotency-Key was already used for a different request.

---

[API](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3.md) - [All operations](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/revisions/a881099bd6c4?raw)