---
title: "Update an extract partially"
method: PATCH
path: "/api/v3/extracts/{id}"
tags: ["Extracts"]
---

# Update an extract partially

`PATCH /api/v3/extracts/{id}`

## Request

- Base URL: `https://embedded.improvado.io`
- URL: `https://embedded.improvado.io/api/v3/extracts/{id}`
- 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/:id/patch.ts> (a function with typed inputs; its response is checked against the schema)

Partially update extraction configuration; omitted top-level fields retain their values. custom_fields and its dynamic_fields alias accept lists of dynamic-field names. Omitting both or supplying [] preserves the dynamic-field selection; [] does not deselect all fields. When both aliases are supplied, their sets of names must match or the request returns 400. Source discovery and compatibility validation apply; changing dynamic dimensions is rejected. Historical dates are validated against the agency's historical-depth limit before mutation. Responses retain the existing custom_fields object representation.

## Path parameters

- `id` integer, required

## Request body

- object
  - `scheduling` 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
  - `fields` string[]
  - `additional_params` object
  - `custom_fields` string[]: Dynamic-field names to select. Optional; omission or [] keeps the existing selection. custom_fields and dynamic_fields are aliases; when both are supplied their sets must match.
  - `dynamic_fields` string[]: Dynamic-field names to select. Optional; omission or [] keeps the existing selection. custom_fields and dynamic_fields are aliases; when both are supplied their sets must match.
  - `sync_historical_data` string, date, nullable

## Response `200`

Partially Update an Extract

- Extract: Extract object
  - `id` integer: Extract ID
  - `title` string: Extract title
  - `connection_id` integer: Connection ID
  - `account_id` integer: Account ID
  - `account_name` string: Account name
  - `account_entity_id` integer: Internal Improvado account entity ID.
  - `account_embedded_id` integer, nullable: Embedded account ID. Null if the account is not linked to an embedded account.
  - `template` object
    - `id` integer: Extract Template ID
    - `title` string: Extract Template title
    - `datasource_name` string: Data source name
    - `data_class` string: Data class
    - `is_wide_template` boolean: Whether the template is a wide report template
  - `data_table` object
    - `id` integer: Data Table ID
    - `name` string: Data Table name
    - `title` string: Data Table title
  - `fields` Field[]
    - `title` string: Field title
    - `name` string: Field name
    - `user_kind` string: Field kind
    - `user_type` string: Field type
    - `selected` boolean: Is the field selected
    - `can_edit` boolean: Can the field be edited
    - `sql_name` string: Sql Name of a Field
    - `format` 'string' | 'float' | 'integer' | 'iso_8601_date' | 'currency' | 'percent' | 'duration' | 'url' | 'image_url': Hint on how the value is meant to be rendered — not a storage contract. Metrics fall back to `float` whenever a data source does not declare a format explicitly, so `float` does not imply the value is fractional, and no decimal precision is guaranteed: values are passed through exactly as the data source returns them, without rounding. New formats may be added over time, so treat an unrecognised value as an unformatted string rather than failing.
    - `is_dynamic` boolean: Is the field dynamic
  - `custom_fields` object[]: Discovered dynamic-field objects, including their name and is_selected state. This response representation is distinct from the list of names accepted in updates.
    - `name` string
    - `title` string
    - `sql_name` string
    - `kind` string
    - `is_selected` boolean
  - `created_at` string: Extract creation date
  - `last_sync` string: Last sync date
  - `status` string: Extract status
  - `error_text` string: Error text
  - `schedules_limit` integer: Schedules limit
  - `scheduling` Scheduling[]
    - `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: Hour at which the run will start (0–23)
    - `minutes` integer: 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
  - `additional_params` AdditionalParams[]
    - `type` string: Additional Params type
    - `name` string: Additional Params name
    - `required` boolean: Is the Additional Params required
    - `title` string: Additional Params title
    - `description` string: Additional Params description
    - `params` object: Additional Params params
    - `initial_value` string: Additional Params initial value
  - `sync_historical_data` string, nullable: Start date for historical data backfill (ISO date format, e.g. "2025-02-25"). Null if not set.

## Other responses

- `400`: Bad Request
- `401`: Forbidden

---

[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)