> ## 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. # Dispatch pause & resume > Hold and release outbound dispatch at global, Domain, lane, or batch scope — endpoints, bounds, and error cases These endpoints hold and release outbound dispatch. Read [Dispatch pacing](/concepts/dispatch-pacing) first for the model: what each scope holds, why pause is never cancel, and how automatic backoffs share the same records. Access follows one rule everywhere: **pause and resume writes require an admin role** on your organization; listings and single-record reads are open to any organization member. A Domain, batch, or pause ID that belongs to another organization returns `404`, never `403`. ## The pause record Every endpoint below reads or writes the same record shape: ```json theme={null} { "id": "pause_9f2c1a7b3d4e5f60", "scope": "domain", "tenancy_id": "ten_9f2c1a7b3d4e5f60", "lane": null, "bucket": null, "batch_id": null, "status": "active", "cause": "admin_request", "reason": "Provider maintenance window", "created_by": "user_11223344", "created_at": "2026-07-29T12:00:00Z", "expires_at": "2026-07-29T13:00:00Z", "released_at": null, "released_by": null, "extensions": [] } ``` | Field | Meaning | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `scope` | `global`, `domain`, `lane`, `bucket`, or `batch`. Exactly one target field below is set to match. | | `tenancy_id` / `lane` / `bucket` / `batch_id` | What is held. `bucket`-scope records are opened only by automatic rate-limit backoff — you cannot create one. | | `status` | `active` while the hold is in force, `released` afterwards. Releasing never deletes; the record survives as the audit trail. | | `cause` | Machine-readable origin: `admin_request` for a human hold, a provider fault tag for an automatic backoff. | | `reason` | The optional human note supplied at pause time. | | `created_by`, `created_at` | Who opened the hold and when. API-key callers are attributed as the account. | | `expires_at` | The scheduled automatic resume, if a duration was given; `null` for an open-ended hold. | | `released_at`, `released_by` | Set once the hold is released — by an admin, or by the scheduler when `expires_at` passes. | | `extensions` | One entry per time the scheduled resume was pushed out. | ### Pause request body All create endpoints accept the same body; every field is optional. | Field | Constraints | | ------------------ | ------------------------------------------------------------------------------------------------------------- | | `duration_seconds` | Integer, `1` to `604800` (one week). Schedules an automatic resume; omit for an open-ended hold. | | `reason` | String, at most `500` characters. Free-text audit note. | | `lane` | Domain endpoint only — one of `backfill`, `bulk`, `compliance`, `interactive`. Narrows the hold to that lane. | | `bucket` | Never accepted on these endpoints (`422`) — bucket holds are the automatic backoff's shape. | ## Global (break-glass) Holds every Domain in your organization at once. Prefer the Domain, lane, or batch endpoints when anything narrower will do. | Method | Endpoint | Access | Success | | ------ | ----------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------- | | `POST` | `/admin/dispatch/pause` | Admin | `201` — the new `global`-scope record | | `POST` | `/admin/dispatch/resume` | Admin | `200` — the released records (`[]` when nothing was held) | | `GET` | `/admin/dispatch/pauses` | Any member | `200` — a page of your organization's pause records, **all scopes**, admin holds and automatic backoffs alike | | `GET` | `/admin/dispatch/pauses/{pause_id}` | Any member | `200` — one record with its full audit trail | The break-glass pause accepts `duration_seconds` and `reason` only. A body carrying `lane` or `bucket` is refused with `422` rather than silently widened to global — if you meant a narrower hold, use the narrower endpoint. Resume releases **every** active global hold and returns them; holds at Domain, lane, or batch scope are untouched. It is idempotent: resuming when nothing is held returns an empty list, not an error. ```bash theme={null} curl -X POST "$BASE_URL/admin/dispatch/pause" \ -H "X-API-Key: $GETDIALED_API_KEY" \ -H "Content-Type: application/json" \ -d '{"duration_seconds": 3600, "reason": "Provider maintenance window"}' ``` The listing supports `include_released` (default `false`), a `scope` filter, `sort_by` (`created_at` or `expires_at`), `order` (`asc`/`desc`, default `desc`), and `limit` (1–500, default 100) / `skip` pagination. ## Domain and lane Holds one Five9 Domain — or one named lane on it. These are records only: no batch document is rewritten and nothing in the queue is touched; the hold is visible here and on the pause listing. | Method | Endpoint | Access | Success | | ------- | --------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------- | | `POST` | `/platforms/five9/domains/{tenancy_id}/pause` | Admin | `201` — a `domain`-scope record, or a `lane`-scope record when the body carries `lane` | | `POST` | `/platforms/five9/domains/{tenancy_id}/resume` | Admin | `200` — the released records (`[]` when nothing was held) | | `GET` | `/platforms/five9/domains/{tenancy_id}/pauses` | Any member | `200` — a page of this Domain's holds, admin holds and automatic backoffs alike | | `PATCH` | `/platforms/five9/domains/{tenancy_id}/pauses/{pause_id}` | Admin | `200` — the extended record | Pausing without `lane` holds the whole Domain; with `lane`, only that lane, while the rest of the Domain keeps flowing. A `bucket` in the body is refused with `422` — bucket holds are opened automatically by rate-limit backoff and cannot be created here. Resume mirrors pause's scoping: without a lane it releases the Domain-wide holds only; with `?lane=bulk` (query parameter) it releases that lane's holds only, leaving any Domain-wide hold in force. An unknown lane is a `422`. Automatic backoffs are never released here — they self-resume at the window boundary. ```bash theme={null} curl -X POST "$BASE_URL/platforms/five9/domains/ten_9f2c1a7b3d4e5f60/pause" \ -H "X-API-Key: $GETDIALED_API_KEY" \ -H "Content-Type: application/json" \ -d '{"lane": "bulk", "reason": "Campaign under review"}' ``` ### Extending a scheduled resume `PATCH .../pauses/{pause_id}` pushes a pause's scheduled resume further out, **in place** — the record keeps its identity and gains an entry in `extensions`. Provide `duration_seconds` (relative to now) or an absolute `expires_at`; when both are sent, the absolute `expires_at` wins. Extension is forward-only. Three cases return `409`, each with its own message: the record is already released; the requested expiry is not later than the current one; or the record changed concurrently between your read and the write. Shortening a hold is an explicit resume-and-re-pause, never a silent edit. An explicit JSON `null` for a field is rejected with `422` — omit the field instead. ```bash theme={null} curl -X PATCH "$BASE_URL/platforms/five9/domains/ten_9f2c1a7b3d4e5f60/pauses/pause_9f2c1a7b3d4e5f60" \ -H "X-API-Key: $GETDIALED_API_KEY" \ -H "Content-Type: application/json" \ -d '{"duration_seconds": 1800}' ``` ## Batch The one scope that touches a batch's status: pausing flips the batch to `paused`, and resuming restores the exact status it held before — a batch paused while `queued` goes back to `queued`. Nothing is cancelled or deleted, and nothing already sent can be re-sent. | Method | Endpoint | Access | Success | | ------ | ---------------------------- | ------ | --------------------------------------------------------- | | `POST` | `/batches/{batch_id}/pause` | Admin | `201` — the `batch`-scope record | | `POST` | `/batches/{batch_id}/resume` | Admin | `200` — the released records (`[]` when nothing was held) | The pause body accepts `duration_seconds` and `reason` only; `lane` or `bucket` is refused with `422` — those scopes belong to the Domain endpoints. Pausing an already-paused batch is idempotent and returns the existing hold. A batch in a terminal state (`completed`, `partially_failed`, `failed`, `cancelled`) has nothing left to dispatch and returns `409`; a `409` also comes back if the batch's status changed concurrently while the pause was being applied — re-read the batch and retry. ```bash theme={null} curl -X POST "$BASE_URL/batches/batch_53c124a15e6e47fe/pause" \ -H "X-API-Key: $GETDIALED_API_KEY" \ -H "Content-Type: application/json" \ -d '{"reason": "Uploaded against the wrong list"}' ``` ## Errors All endpoints use the standard `{"detail": "..."}` envelope. | Status | When | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401` | Missing or invalid credentials. | | `403` | Authenticated but not an admin, on any pause/resume/extend write. | | `404` | The Domain, batch, or pause does not exist — or belongs to another organization (never `403`). | | `409` | Extension refused (released record, non-later expiry, or concurrent change), or a batch pause hit a terminal/concurrently-changed batch. | | `422` | Validation: `duration_seconds` outside `1`–`604800`, `reason` over `500` characters, an unknown `lane`, a `bucket` in any body, `lane`/`bucket` on the global or batch endpoints, or an explicit `null` on the extension PATCH. | | `429` | Request rate limit exceeded — retry after the `Retry-After` header. |