> ## Documentation Index > Fetch the complete documentation index at: https://docs.getdialed.ai/llms.txt > Use this file to discover all available pages before exploring further. # Change a batch's priority or pacing > Re-order or re-pace a batch that is already queued or in flight — fields, bounds, worked examples, and error cases This endpoint changes **how** a batch's remaining work is dispatched, without cancelling and re-submitting it. Read [Dispatch pacing](/concepts/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. ```bash theme={null} 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. ```bash theme={null} 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. ```bash theme={null} 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: ```json theme={null} { "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 Lane order, the starvation floor, coalescing, and the paced-release model. Hold dispatch entirely instead of re-pacing it. Every status a batch moves through, including which ones are terminal. The Domain record whose rate buckets and margins set the rate a policy must beat.