---
title: "Update Bulk Sync"
method: PUT
path: "/api/bulk/syncs/{id}"
tags: ["Bulk Sync"]
---

# Update Bulk Sync

`PUT /api/bulk/syncs/{id}`

Updates an existing bulk sync's top-level configuration.

Updating a bulk sync is a **full replacement** of the sync's top-level
configuration. Every field in the request body is written to the sync; any
field you omit is cleared or reset to its default value.

To make a partial change — for example, toggling `active` or swapping a
schedule — fetch the current sync with
[`GET /api/bulk/syncs/{id}`](../../../../api-reference/bulk-sync/get),
modify the fields you want to change, and send the complete object back in
the update request.

Updates to `active`, `schedules`, and `policies` take effect immediately.
Changes to source or destination configuration take effect on the sync's
next execution.

Because omitted fields are reset to their defaults, the discovery and
naming options behave the same as on create when left out:

- `automatically_add_new_objects` resets to not enabling newly discovered
  source objects automatically.
- `automatically_add_new_fields` resets to enabling newly discovered
  fields on already selected objects.
- `normalize_names` resets to enabled.

Send the existing values explicitly if you want to preserve a non-default or
non-empty setting, including schema and field selections.

> 📘 Updating schemas
>
> Schema updates are not performed through this endpoint. Use the
> [Update Bulk Sync Schemas](../../../../api-reference/bulk-sync/schemas/patch)
> endpoint to change a subset of schemas, or
> [Update Bulk Sync Schema](../../../../api-reference/bulk-sync/schemas/update)
> to replace a single schema's configuration.

## Path parameters

- `id` string, uuid, required — Unique identifier of the bulk sync to update.

## Headers

- `X-Polytomic-Version` string

## Request body

- UpdateBulkSyncRequest
  - `active` boolean, nullable — Whether the sync is active. Inactive syncs do not run on their schedule but can still be triggered manually.
  - `additional_schedules` BulkSyncAdditionalScheduleRequest[], nullable — Additional bulk sync schedules. Schedule times are interpreted in UTC.
    - `day_of_month` string — Day of the month (1-31) to run monthly schedules.
    - `day_of_week` string — Day of the week to run weekly schedules.
    - `frequency` 'manual' | 'continuous' | 'hourly' | 'daily' | 'weekly' | 'custom' | 'builder' | 'runafter' | 'multi' | 'dbtcloud', required
    - `hour` string — Hour of the day (0-23, in UTC) to run hourly, daily, weekly, or monthly schedules.
    - `id` string, uuid
    - `minute` string — Minute of the hour (0-59) to run the schedule.
    - `month` string — Month of the year (1-12) to run yearly schedules.
    - `resync_mode` 'normal' | 'refetch' | 'resync' | 'rebuild'
    - `schemas` string[] — Optional list of schema IDs this schedule applies to. If empty, the schedule applies to all schemas.
    - `selective_mode` 'none' | 'incrementalFields' | 'nonincrementalFields'
  - `automatically_add_new_fields` 'all' | 'onlyIncremental' | 'onlyNonIncremental' | 'none', nullable
  - `automatically_add_new_objects` 'all' | 'onlyIncremental' | 'onlyNonIncremental' | 'none', nullable
  - `concurrency_limit` integer, nullable — Override the default concurrency limit for this sync.
  - `data_cutoff_timestamp` string, date-time, nullable — Global cutoff applied across schemas. Source records older than this timestamp are excluded from sync runs.
  - `default_schedule` BulkSyncDefaultScheduleRequest, required
    - `day_of_month` string — Day of the month (1-31) to run monthly schedules.
    - `day_of_week` string — Day of the week to run weekly schedules.
    - `frequency` 'manual' | 'continuous' | 'hourly' | 'daily' | 'weekly' | 'custom' | 'builder' | 'runafter' | 'multi' | 'dbtcloud', required
    - `hour` string — Hour of the day (0-23, in UTC) to run hourly, daily, weekly, or monthly schedules.
    - `id` string, uuid
    - `minute` string — Minute of the hour (0-59) to run the schedule.
    - `month` string — Month of the year (1-12) to run yearly schedules.
  - `destination_configuration` object, required — Destination-specific bulk sync configuration (e.g. output schema name, file format). The accepted keys depend on the destination connection type.
  - `destination_connection_id` string, uuid, required — Unique identifier of the connection rows are written to.
  - `disable_record_timestamps` boolean, nullable — When true, Polytomic will not add its own timestamp columns to destination rows.
  - `mode` 'snapshot' | 'replicate', nullable, required
  - `name` string, required — Human-readable name for the bulk sync.
  - `normalize_names` 'enabled' | 'disabled' | 'legacy', nullable
  - `organization_id` string, uuid, nullable — Organization the sync belongs to. Only used by partner callers; normal callers are always scoped to their own organization.
  - `policies` string[], nullable — Identifiers of permissions policies applied to the bulk sync.
  - `resync_concurrency_limit` integer, nullable — Override the default resync concurrency limit for this sync.
  - `schemas` union[], nullable — List of schemas to sync; if omitted, all schemas will be selected for syncing.
    - union
      - string
      - SchemaConfiguration
        - `data_cutoff_timestamp` string, date-time, nullable
        - `disable_data_cutoff` boolean, nullable — Whether data cutoff is disabled for this schema.
        - `enabled` boolean, nullable — Whether the schema is enabled for syncing.
        - `fields` union[]
          - union
            - string
            - FieldConfiguration
              - …
        - `filters` BulkFilter[]
          - `field_id` string — Schema field ID to filter on.
          - `function` 'Equality' | 'Inequality' | 'IsNull' | 'IsNotNull' | 'True' | 'False' | 'OnOrAfter' | 'OnOrBefore' | 'GreaterThan' | 'GreaterThanEqual' | 'LessThan' | 'LessThanEqual' | 'StringContains' | 'StringStartsWith' | 'StringEndsWith' | 'StringDoesNotContain' | 'StringDoesNotStartWith' | 'StringDoesNotEndWith' | 'StringOneOf' | 'StringNotOneOf' | 'Between' | 'ArrayContains' | 'ArrayDoesNotContain' | 'InTheLast' | 'RelativeOnOrBefore' | 'RelativeOnOrAfter' | 'StringLike' | 'StringNotLike' | 'StringMatchesTrimmed', required
          - `value` string
        - `id` string
        - `partition_key` string, nullable
        - `tracking_field` string, nullable
  - `source_configuration` object, nullable — Source-specific bulk sync configuration (e.g. replication slot name, sync lookback). The accepted keys depend on the source connection type.
  - `source_connection_id` string, uuid, required — Unique identifier of the connection rows are read from.

## Response `200`

OK

- BulkSyncResponseEnvelope
  - `data` BulkSyncResponse
    - `active` boolean — Whether the sync is active. Inactive syncs do not run on their schedule.
    - `additional_schedules` BulkSyncAdditionalScheduleResponse[], nullable — Additional bulk sync schedules. Schedule times are interpreted in UTC.
      - `created_at` string, date-time — Timestamp the schedule was created.
      - `created_by` OutputActor
        - `id` string, uuid
        - `name` string
        - `type` string
      - `day_of_month` string — Day of the month (1-31) for monthly schedules.
      - `day_of_week` string — Day of the week for weekly schedules.
      - `frequency` 'manual' | 'continuous' | 'hourly' | 'daily' | 'weekly' | 'custom' | 'builder' | 'runafter' | 'multi' | 'dbtcloud', required
      - `hour` string — Hour of the day (0-23, in UTC) the schedule fires.
      - `id` string, uuid — Unique identifier of the schedule.
      - `minute` string — Minute of the hour (0-59) the schedule fires.
      - `month` string — Month of the year (1-12) for yearly schedules.
      - `resync_mode` 'normal' | 'refetch' | 'resync' | 'rebuild'
      - `schemas` string[] — Schema IDs this schedule applies to. Empty means all schemas.
      - `selective_mode` 'none' | 'incrementalFields' | 'nonincrementalFields'
      - `updated_at` string, date-time — Timestamp the schedule was last updated.
      - `updated_by` OutputActor
        - `id` string, uuid
        - `name` string
        - `type` string
    - `automatically_add_new_fields` 'all' | 'onlyIncremental' | 'onlyNonIncremental' | 'none', nullable
    - `automatically_add_new_objects` 'all' | 'onlyIncremental' | 'onlyNonIncremental' | 'none', nullable
    - `concurrency_limit` integer, nullable — Per-sync concurrency limit override.
    - `created_at` string, date-time — Timestamp the sync was created.
    - `created_by` OutputActor
      - `id` string, uuid
      - `name` string
      - `type` string
    - `data_cutoff_timestamp` string, date-time, nullable — Global cutoff applied across schemas; source records older than this timestamp are excluded.
    - `default_schedule` BulkSyncDefaultScheduleResponse
      - `created_at` string, date-time — Timestamp the schedule was created.
      - `created_by` OutputActor
        - `id` string, uuid
        - `name` string
        - `type` string
      - `day_of_month` string — Day of the month (1-31) for monthly schedules.
      - `day_of_week` string — Day of the week for weekly schedules.
      - `frequency` 'manual' | 'continuous' | 'hourly' | 'daily' | 'weekly' | 'custom' | 'builder' | 'runafter' | 'multi' | 'dbtcloud', required
      - `hour` string — Hour of the day (0-23, in UTC) the schedule fires.
      - `id` string, uuid — Unique identifier of the schedule.
      - `minute` string — Minute of the hour (0-59) the schedule fires.
      - `month` string — Month of the year (1-12) for yearly schedules.
      - `updated_at` string, date-time — Timestamp the schedule was last updated.
      - `updated_by` OutputActor
        - `id` string, uuid
        - `name` string
        - `type` string
    - `destination_configuration` object, nullable — Destination-specific bulk sync configuration. e.g. output schema name, s3 file format, etc.
    - `destination_connection_id` string, uuid — Connection rows are written to.
    - `disable_record_timestamps` boolean — When true, Polytomic does not add its own timestamp columns to destination rows.
    - `id` string, uuid — Unique identifier of the bulk sync.
    - `mode` 'snapshot' | 'replicate', nullable
    - `name` string — Human-readable name of the bulk sync.
    - `normalize_names` 'enabled' | 'disabled' | 'legacy', nullable
    - `organization_id` string, uuid — Organization the sync belongs to.
    - `policies` string[] — List of permissions policies applied to the bulk sync.
    - `resync_concurrency_limit` integer, nullable — Per-sync resync concurrency limit override.
    - `source_configuration` object, nullable — Source-specific bulk sync configuration. e.g. replication slot name, sync lookback, etc.
    - `source_connection_id` string, uuid — Connection rows are read from.
    - `updated_at` string, date-time — Timestamp the sync was last updated.
    - `updated_by` OutputActor
      - `id` string, uuid
      - `name` string
      - `type` string

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `404` — Not Found
- `500` — Internal Server Error

---

[API](https://skmtc.net/polytomic/apis/polytomic-api.md) · [All operations](https://skmtc.net/polytomic/apis/polytomic-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/polytomic/polytomic-api/versions/5e9bcd4cfb2d/schema)