---
title: "Pause a bulk job"
method: POST
path: "/v1/bulk/jobs/{jobId}/pause"
---

# Pause a bulk job

`POST /v1/bulk/jobs/{jobId}/pause`

## Request

- Base URL: `https://docs.greatwait.dev` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.greatwait.dev/v1/bulk/jobs/{jobId}/pause`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer and API key in header `Greatwait-Environment` and API key in header `Greatwait-Project`

Controls remaining bulk-job work with a mandatory expectedVersion fence and current resolved-action authorization. Already-started items may finish; completed callbacks and history remain. This does not pause the selected schedules.

## Path parameters

- `jobId` string, required

## Request body

- object
  - `expectedVersion` integer, required

## Response `200`

Pause a bulk job

- object
  - `id` string, required
  - `authority` object, required
    - `environment` string, required
    - `environmentKind` 'test' | 'live', required
    - `organization` string, required
    - `project` string, required
  - `intent` union, required
    - object
      - `target` 'schedules' | 'parent_schedules' | 'occurrences', required
      - `selection` union, required
        - object
          - `kind` 'ids', required
          - `resource` 'schedules', required
          - `ids` string[], required
        - object
          - `kind` 'ids', required
          - `resource` 'executions', required
          - `ids` string[], required
        - object
          - `kind` 'all_matching', required
          - `resource` 'schedules', required
          - `filter` object, required
            - `external_identifier` string: Host application identifier, matched exactly and case-sensitively; at most 256 UTF-8 bytes. Readable by schedule readers; do not include secrets.
            - `tag` string: An exact, case-sensitive tag of at most 64 UTF-8 bytes.
            - `status` 'active' | 'paused' | 'cancelled' | 'completed'
            - `recurrence` 'at' | 'every' | 'cron'
            - `endpoint` union
              - …
            - `text` string: Case-insensitive literal substring of schedule name, endpoint address or schedule identifier.
            - `schedule` string
            - `dueAfter` string
            - `dueBefore` string
        - object
          - `kind` 'all_matching', required
          - `resource` 'executions', required
          - `filter` object, required
            - `external_identifier` string: Host application identifier, matched exactly and case-sensitively; at most 256 UTF-8 bytes. Readable by schedule readers; do not include secrets.
            - `tag` string: An exact, case-sensitive tag of at most 64 UTF-8 bytes.
            - `status` 'active' | 'paused' | 'cancelled' | 'completed'
            - `recurrence` 'at' | 'every' | 'cron'
            - `endpoint` union
              - …
            - `text` string: Case-insensitive literal substring of schedule name, endpoint address or schedule identifier.
            - `schedule` string
            - `from` string
            - `to` string
            - `outcome` 'planned' | 'due' | 'dispatching' | 'retry_wait' | 'ambiguous' | 'succeeded' | 'terminal_failed' | 'cancelled' | 'skipped_stale'
      - `operation` 'retry', required
      - `parameters` object, required
        - `includeSucceeded` boolean
    - object
      - `target` 'schedules' | 'parent_schedules' | 'occurrences', required
      - `selection` union, required
        - object
          - `kind` 'ids', required
          - `resource` 'schedules', required
          - `ids` string[], required
        - object
          - `kind` 'ids', required
          - `resource` 'executions', required
          - `ids` string[], required
        - object
          - `kind` 'all_matching', required
          - `resource` 'schedules', required
          - `filter` object, required
            - `external_identifier` string: Host application identifier, matched exactly and case-sensitively; at most 256 UTF-8 bytes. Readable by schedule readers; do not include secrets.
            - `tag` string: An exact, case-sensitive tag of at most 64 UTF-8 bytes.
            - `status` 'active' | 'paused' | 'cancelled' | 'completed'
            - `recurrence` 'at' | 'every' | 'cron'
            - `endpoint` union
              - …
            - `text` string: Case-insensitive literal substring of schedule name, endpoint address or schedule identifier.
            - `schedule` string
            - `dueAfter` string
            - `dueBefore` string
        - object
          - `kind` 'all_matching', required
          - `resource` 'executions', required
          - `filter` object, required
            - `external_identifier` string: Host application identifier, matched exactly and case-sensitively; at most 256 UTF-8 bytes. Readable by schedule readers; do not include secrets.
            - `tag` string: An exact, case-sensitive tag of at most 64 UTF-8 bytes.
            - `status` 'active' | 'paused' | 'cancelled' | 'completed'
            - `recurrence` 'at' | 'every' | 'cron'
            - `endpoint` union
              - …
            - `text` string: Case-insensitive literal substring of schedule name, endpoint address or schedule identifier.
            - `schedule` string
            - `from` string
            - `to` string
            - `outcome` 'planned' | 'due' | 'dispatching' | 'retry_wait' | 'ambiguous' | 'succeeded' | 'terminal_failed' | 'cancelled' | 'skipped_stale'
      - `operation` 'reschedule', required
      - `parameters` union, required
        - object
          - `mode` 'absolute', required
          - `at` string, required
        - object
          - `mode` 'shift_existing', required
          - `seconds` integer, required
        - object
          - `mode` 'delay_from_reference', required
          - `seconds` integer, required
        - object
          - `mode` 'definition', required
          - `definition` union, required
            - object
              - …
            - object
              - …
    - object
      - `target` 'schedules' | 'parent_schedules' | 'occurrences', required
      - `selection` union, required
        - object
          - `kind` 'ids', required
          - `resource` 'schedules', required
          - `ids` string[], required
        - object
          - `kind` 'ids', required
          - `resource` 'executions', required
          - `ids` string[], required
        - object
          - `kind` 'all_matching', required
          - `resource` 'schedules', required
          - `filter` object, required
            - `external_identifier` string: Host application identifier, matched exactly and case-sensitively; at most 256 UTF-8 bytes. Readable by schedule readers; do not include secrets.
            - `tag` string: An exact, case-sensitive tag of at most 64 UTF-8 bytes.
            - `status` 'active' | 'paused' | 'cancelled' | 'completed'
            - `recurrence` 'at' | 'every' | 'cron'
            - `endpoint` union
              - …
            - `text` string: Case-insensitive literal substring of schedule name, endpoint address or schedule identifier.
            - `schedule` string
            - `dueAfter` string
            - `dueBefore` string
        - object
          - `kind` 'all_matching', required
          - `resource` 'executions', required
          - `filter` object, required
            - `external_identifier` string: Host application identifier, matched exactly and case-sensitively; at most 256 UTF-8 bytes. Readable by schedule readers; do not include secrets.
            - `tag` string: An exact, case-sensitive tag of at most 64 UTF-8 bytes.
            - `status` 'active' | 'paused' | 'cancelled' | 'completed'
            - `recurrence` 'at' | 'every' | 'cron'
            - `endpoint` union
              - …
            - `text` string: Case-insensitive literal substring of schedule name, endpoint address or schedule identifier.
            - `schedule` string
            - `from` string
            - `to` string
            - `outcome` 'planned' | 'due' | 'dispatching' | 'retry_wait' | 'ambiguous' | 'succeeded' | 'terminal_failed' | 'cancelled' | 'skipped_stale'
      - `operation` 'cancel', required
      - `parameters` object, required
    - object
      - `target` 'schedules' | 'parent_schedules' | 'occurrences', required
      - `selection` union, required
        - object
          - `kind` 'ids', required
          - `resource` 'schedules', required
          - `ids` string[], required
        - object
          - `kind` 'ids', required
          - `resource` 'executions', required
          - `ids` string[], required
        - object
          - `kind` 'all_matching', required
          - `resource` 'schedules', required
          - `filter` object, required
            - `external_identifier` string: Host application identifier, matched exactly and case-sensitively; at most 256 UTF-8 bytes. Readable by schedule readers; do not include secrets.
            - `tag` string: An exact, case-sensitive tag of at most 64 UTF-8 bytes.
            - `status` 'active' | 'paused' | 'cancelled' | 'completed'
            - `recurrence` 'at' | 'every' | 'cron'
            - `endpoint` union
              - …
            - `text` string: Case-insensitive literal substring of schedule name, endpoint address or schedule identifier.
            - `schedule` string
            - `dueAfter` string
            - `dueBefore` string
        - object
          - `kind` 'all_matching', required
          - `resource` 'executions', required
          - `filter` object, required
            - `external_identifier` string: Host application identifier, matched exactly and case-sensitively; at most 256 UTF-8 bytes. Readable by schedule readers; do not include secrets.
            - `tag` string: An exact, case-sensitive tag of at most 64 UTF-8 bytes.
            - `status` 'active' | 'paused' | 'cancelled' | 'completed'
            - `recurrence` 'at' | 'every' | 'cron'
            - `endpoint` union
              - …
            - `text` string: Case-insensitive literal substring of schedule name, endpoint address or schedule identifier.
            - `schedule` string
            - `from` string
            - `to` string
            - `outcome` 'planned' | 'due' | 'dispatching' | 'retry_wait' | 'ambiguous' | 'succeeded' | 'terminal_failed' | 'cancelled' | 'skipped_stale'
      - `operation` 'pause', required
      - `parameters` object, required
    - object
      - `target` 'schedules' | 'parent_schedules' | 'occurrences', required
      - `selection` union, required
        - object
          - `kind` 'ids', required
          - `resource` 'schedules', required
          - `ids` string[], required
        - object
          - `kind` 'ids', required
          - `resource` 'executions', required
          - `ids` string[], required
        - object
          - `kind` 'all_matching', required
          - `resource` 'schedules', required
          - `filter` object, required
            - `external_identifier` string: Host application identifier, matched exactly and case-sensitively; at most 256 UTF-8 bytes. Readable by schedule readers; do not include secrets.
            - `tag` string: An exact, case-sensitive tag of at most 64 UTF-8 bytes.
            - `status` 'active' | 'paused' | 'cancelled' | 'completed'
            - `recurrence` 'at' | 'every' | 'cron'
            - `endpoint` union
              - …
            - `text` string: Case-insensitive literal substring of schedule name, endpoint address or schedule identifier.
            - `schedule` string
            - `dueAfter` string
            - `dueBefore` string
        - object
          - `kind` 'all_matching', required
          - `resource` 'executions', required
          - `filter` object, required
            - `external_identifier` string: Host application identifier, matched exactly and case-sensitively; at most 256 UTF-8 bytes. Readable by schedule readers; do not include secrets.
            - `tag` string: An exact, case-sensitive tag of at most 64 UTF-8 bytes.
            - `status` 'active' | 'paused' | 'cancelled' | 'completed'
            - `recurrence` 'at' | 'every' | 'cron'
            - `endpoint` union
              - …
            - `text` string: Case-insensitive literal substring of schedule name, endpoint address or schedule identifier.
            - `schedule` string
            - `from` string
            - `to` string
            - `outcome` 'planned' | 'due' | 'dispatching' | 'retry_wait' | 'ambiguous' | 'succeeded' | 'terminal_failed' | 'cancelled' | 'skipped_stale'
      - `operation` 'resume', required
      - `parameters` object, required
  - `state` 'preparing' | 'awaiting_confirmation' | 'queued' | 'running' | 'paused' | 'blocked' | 'completed' | 'completed_with_failures' | 'cancelled' | 'expired' | 'refused', required
  - `version` integer, required
  - `createdAt` string, required
  - `updatedAt` string, required
  - `referenceAt` string, required
  - `preparationExpiresAt` string, required
  - `previewExpiresAt` string
  - `executionExpiresAt` string
  - `resultsExpireAt` string
  - `intentDigest` string
  - `complete` boolean, required
  - `counts` object, required
    - `matched` integer, required
    - `eligible` integer, required
    - `ineligible` integer, required
    - `pending` integer, required
    - `running` integer, required
    - `succeeded` integer, required
    - `noOp` integer, required
    - `skipped` integer, required
    - `conflicted` integer, required
    - `failed` integer, required
    - `cancelled` integer, required
  - `reasons` object[], required
    - `reason` 'eligible' | 'already_active' | 'already_paused' | 'already_cancelled' | 'invalid_state' | 'unsupported_target' | 'expired_input' | 'unauthorized' | 'concurrently_changed' | 'past_time' | 'attempt_limit' | 'operation_failed' | 'transient_failure' | 'selection_too_large' | 'preparation_incomplete' | 'preview_expired' | 'job_expired' | 'job_cancelled' | 'quota_exceeded' | 'spending_limit' | 'in_flight', required
    - `count` integer, required
  - `warnings` string[], required
  - `samples` object[], required
    - `id` string, required
    - `jobId` string, required
    - `scheduleId` string, required
    - `occurrenceId` string
    - `state` 'pending' | 'running' | 'succeeded' | 'no_op' | 'skipped' | 'conflicted' | 'failed' | 'cancelled', required
    - `reason` 'eligible' | 'already_active' | 'already_paused' | 'already_cancelled' | 'invalid_state' | 'unsupported_target' | 'expired_input' | 'unauthorized' | 'concurrently_changed' | 'past_time' | 'attempt_limit' | 'operation_failed' | 'transient_failure' | 'selection_too_large' | 'preparation_incomplete' | 'preview_expired' | 'job_expired' | 'job_cancelled' | 'quota_exceeded' | 'spending_limit' | 'in_flight', required
    - `eligible` boolean, required
    - `retryable` boolean, required
    - `fence` string, required
    - `before` object, required
      - `status` string
      - `plannedFor` string
      - `recurrence` string
      - `timeZone` string
      - `affectedFutureRuns` integer
      - `latenessPolicy` 'skipAhead' | 'catchUp'
      - `maxStalenessSeconds` integer
      - `overlapPolicy` 'skip' | 'queue'
      - `nextRunNote` string
    - `after` object
      - `status` string
      - `plannedFor` string
      - `recurrence` string
      - `timeZone` string
      - `affectedFutureRuns` integer
      - `latenessPolicy` 'skipAhead' | 'catchUp'
      - `maxStalenessSeconds` integer
      - `overlapPolicy` 'skip' | 'queue'
      - `nextRunNote` string
    - `attemptId` string
    - `actionId` string
    - `updatedAt` string, required
    - `expiresAt` string
  - `limits` object, required
    - `maxTargets` integer, required
    - `executionLifetimeSeconds` integer, required
    - `previewLifetimeSeconds` integer, required
    - `resultRetentionSeconds` integer, required
    - `batchSize` integer, required
    - `workerConcurrency` integer, required
  - `billing` object, required
    - `additionalAttemptsMinimum` integer, required
    - `additionalAttemptsMaximum` integer
    - `currentLimits` object
      - `capturedAt` string, required
      - `billingMode` 'disabled' | 'shadow' | 'enforced', required
      - `attemptsPerOccurrence` integer, required
      - `dailyAttemptQuota` 'none', required
      - `availableCreditMicrodollars` string
      - `spendingCapMicrodollars` string, nullable
      - `remainingToSpendingCapMicrodollars` string
    - `exactChargeKnown` false, required
    - `note` string, required
  - `reason` 'eligible' | 'already_active' | 'already_paused' | 'already_cancelled' | 'invalid_state' | 'unsupported_target' | 'expired_input' | 'unauthorized' | 'concurrently_changed' | 'past_time' | 'attempt_limit' | 'operation_failed' | 'transient_failure' | 'selection_too_large' | 'preparation_incomplete' | 'preview_expired' | 'job_expired' | 'job_cancelled' | 'quota_exceeded' | 'spending_limit' | 'in_flight'

## Other responses

- `400`: Problem document. Possible codes at this status: invalid_request.
- `401`: Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked.
- `404`: Problem document. Possible codes at this status: not_found.
- `409`: Problem document. Possible codes at this status: project_archived, state_conflict, version_conflict.
- `429`: Problem document. Possible codes at this status: rate_limited.
- `503`: Problem document. Possible codes at this status: capability_not_configured, service_unavailable.

---

[API](https://skmtc.dev/greatwait/apis/greatwait-v1.md) · [All operations](https://skmtc.dev/greatwait/apis/greatwait-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/greatwait/apis/greatwait-v1/revisions/6855bce23e72?raw)