Change a batch's priority or pacing

This endpoint changes how a batch’s remaining work is dispatched, without cancelling and re-submitting it. Read Dispatch pacing first for the model: what a lane is, why priority is a within-lane boost rather than a lane override, and why a paced release never bursts to catch up. Access is the one rule worth stating up front: any organization API key may call this — there is no admin role requirement. A priority boost only re-orders how your own account’s provider budget is spent, and a pacing policy only ever slows your own batch down, so neither can affect another account or take capacity from another lane. A batch ID belonging to another organization returns 404, never 403.

Method	Endpoint	Access	Success
`PATCH`	`/flows/batches/{batch_id}`	Any member	`200` — the updated batch record

Request body

Every field is optional. Send only what you are changing; an empty body {} leaves the batch untouched and returns it unchanged, without advancing updated_at.

Field	Type	Meaning
`priority`	`"normal"` or `"high"`	Re-orders this batch’s remaining work within its own dispatch lane.
`pacing`	object	Sets or replaces the release policy — `records_per_period` every `period_minutes`, with an optional `window`.
`remove_pacing`	boolean, default `false`	Send `true` to stop pacing the batch entirely.

An explicit JSON null is rejected with 422 rather than treated as a removal — omit a field to leave it unchanged. That is why remove_pacing exists: {"pacing": null} is ambiguous between “unchanged” and “remove it”, so removal gets its own unambiguous flag. Sending pacing and remove_pacing: true together is refused for the same reason — it states two intentions at once.

Pacing policy fields

Field	Constraints
`records_per_period`	Integer, `1` to `1000000`. The ceiling on records released per period.
`period_minutes`	Integer, `1` to `1440`. Whole minutes only — a sub-minute pace cannot be expressed, because provider limits are themselves measured per minute.
`window`	Optional object confining delivery to particular local hours (below). Omit to deliver around the clock.

Delivery window fields

Field	Constraints
`timezone`	Required whenever a window is used. An IANA zone name such as `America/Denver`. There is no default, and a fixed UTC offset is not accepted — a named zone keeps the window daylight-saving-correct. An unknown name is a `422`.
`start_minute_of_day`	Integer, `0` to `1439`. Minutes since local midnight, inclusive.
`end_minute_of_day`	Integer, `1` to `1440`. Minutes since local midnight, exclusive; `1440` means the local midnight that ends the day. Must be later than the start — a window that would wrap past midnight is refused.
`days`	Optional list of lowercase weekday names (`monday` … `sunday`). Omit for every day.

Semantics worth getting right

Three behaviours account for most surprises:

A priority change applies only to work not yet claimed. The rewrite targets this batch’s still-queued dispatch work; anything already claimed or already sent is untouched, because a call that has left cannot be re-ordered. On a batch whose work is nearly all dispatched, a boost may therefore change very little — that is correct, not a failure. Boosted work stays in its lane, so it still merges with that lane’s other work.
A pacing change applies from the next release tick, with no burst. Slowing a batch down never recalls records already released. Speeding one up never releases a backlog all at once to make up the difference — the new rate simply takes effect going forward. The same holds for remove_pacing: the batch reverts to full budget rate from that point, not with a catch-up surge.
A policy must be strictly slower than the rate already available. A pacing policy is a throttle, so one at or above the batch’s effective rate is refused with 422 rather than quietly clamped — the message names both the rate you asked for and the rate already available. Clamping would leave your stated policy and the system’s actual behaviour permanently out of step with no signal. The comparison uses the budget after your Domain’s safety margin, never the provider’s raw cap.

Both knobs are echoed on every batch read, so a GET /flows/batches/{batch_id} confirms what is actually in force. priority reads null on a batch that never asked for a boost and pacing reads null on an unpaced batch.

Raise a batch’s priority

Moves this batch ahead of the rest of its lane’s queued work.

curl -X PATCH "$BASE_URL/flows/batches/batch_53c124a15e6e47fe" \
  -H "X-API-Key: $GETDIALED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"priority": "high"}'

Pace a batch inside a delivery window

Releases at most 5,000 records every 15 minutes, and only between 09:00 and 17:00 Mountain time on weekdays. Records still queued when the window closes resume at 09:00 the next weekday — never rushed, never dropped.

curl -X PATCH "$BASE_URL/flows/batches/batch_53c124a15e6e47fe" \
  -H "X-API-Key: $GETDIALED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "pacing": {
          "records_per_period": 5000,
          "period_minutes": 15,
          "window": {
            "timezone": "America/Denver",
            "start_minute_of_day": 540,
            "end_minute_of_day": 1020,
            "days": ["monday", "tuesday", "wednesday", "thursday", "friday"]
          }
        }
      }'

Stop pacing a batch

The batch returns to delivering as fast as its provider budget allows, from that moment forward.

curl -X PATCH "$BASE_URL/flows/batches/batch_53c124a15e6e47fe" \
  -H "X-API-Key: $GETDIALED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"remove_pacing": true}'

Response

200 returns the full batch record, including both scheduling knobs:

{
  "id": "batch_53c124a15e6e47fe",
  "definition_id": "def_a1b2c3d4",
  "org_id": "org_a1b2c3d4",
  "trigger_id": "trigger_44556677",
  "trigger_type": "api_call",
  "trigger_source": null,
  "schedule_id": null,
  "metadata": { "campaign": "spring-2026" },
  "status": "running",
  "record_count": 250000,
  "scheduled_at": null,
  "started_at": "2026-07-09T18:00:00Z",
  "completed_at": null,
  "created_at": "2026-07-09T17:59:59Z",
  "updated_at": "2026-07-09T18:04:11Z",
  "priority": "high",
  "pacing": {
    "records_per_period": 5000,
    "period_minutes": 15,
    "window": {
      "timezone": "America/Denver",
      "start_minute_of_day": 540,
      "end_minute_of_day": 1020,
      "days": ["monday", "tuesday", "wednesday", "thursday", "friday"]
    }
  }
}

Errors

The standard {"detail": "..."} envelope.

Status	When
`401`	Missing or invalid credentials.
`404`	The batch does not exist — or belongs to another organization, which returns `404` rather than `403` so the response cannot confirm that someone else’s batch exists. Also returned if the batch is deleted between the read and the write.
`409`	The batch is in a terminal state (`completed`, `partially_failed`, `failed`, `cancelled`) and has nothing left to re-order or re-pace. Note that `paused` is not terminal — re-ordering a held batch before releasing it is exactly what this endpoint is for.
`422`	Validation: an explicit `null` on `priority` or `pacing`; an unknown `priority` value; `pacing` and `remove_pacing` sent together; `records_per_period` or `period_minutes` out of bounds; an unknown or missing window `timezone`; a window whose end is not after its start; or a pacing policy that is not strictly slower than the effective rate already available to the batch.
`429`	Request rate limit exceeded — retry after the `Retry-After` header.

Next steps

Dispatch pacing

Lane order, the starvation floor, coalescing, and the paced-release model.

Pause & resume API

Hold dispatch entirely instead of re-pacing it.

Batches, jobs, and executions

Every status a batch moves through, including which ones are terminal.

Platform tenancy

The Domain record whose rate buckets and margins set the rate a policy must beat.

Overview

Flows — /v1/flows

Account — /v1/account

Data — /v1/data

Catalog — /v1/catalog

Credentials — /v1/credentials

Tenants — /v1/tenants

Five9 Domains — /v1/platforms/five9

Admin — /v1/admin

Change a batch's priority or pacing

Request body

Pacing policy fields

Delivery window fields

Semantics worth getting right

Raise a batch’s priority

Pace a batch inside a delivery window

Stop pacing a batch

Response

Errors

Next steps

Dispatch pacing

Pause & resume API

Batches, jobs, and executions

Platform tenancy

​Request body

​Pacing policy fields

​Delivery window fields

​Semantics worth getting right

​Raise a batch’s priority

​Pace a batch inside a delivery window

​Stop pacing a batch

​Response

​Errors

​Next steps

Dispatch pacing

Pause & resume API

Batches, jobs, and executions

Platform tenancy

Request body

Pacing policy fields

Delivery window fields

Semantics worth getting right

Raise a batch’s priority

Pace a batch inside a delivery window

Stop pacing a batch

Response

Errors

Next steps