What's new ⬇ Download Reportworq
⬇ Guide PDF

Pause and resume by API#

These commands control the global execution pause from outside Reportworq: pause all job execution, check the pause, resume, and cancel what is running. They are part of the /api/v1 Local API, so the base address, the access token and the license gate are the same as for run.

Before you begin#

Try it in Reportworq. A system administrator can send pause, pause/status, resume and cancelall from the built-in API tester (Settings, Integrations, API tester) with the query parameters ready to edit: see Try the API in Reportworq. Remember that a real pause pauses the whole server.

The commands#

Command Method Query string Returns
pause POST duration, waitForPause, waitSeconds (all optional) result, holdId and status
pause/status GET or POST none the pause status
resume POST holdId (optional) the pause status, with releasedHoldCount
cancelall POST includePending, pendingOnly (both optional) the number of jobs canceled and their execution ids

A value that is not valid answers 400 with a message that names the parameter.

Pause#

Pauses all job execution. New jobs stay Pending and running jobs hold at their next data-source query or step. Each call adds a pause (a hold) with its own holdId. Reportworq stays paused while any hold is active.

Parameter Meaning
duration The number of minutes to stay paused, greater than 0 and at most 525600. The time counts from the moment every running job is paused. Leave it out to pause until a resume.
waitForPause true to wait until every running job is paused before answering. Default false.
waitSeconds With waitForPause, how long to wait, a whole number from 1 to 300. Default 300.

Request

POST https://localhost:8600/api/v1/pause?duration=30&waitForPause=true&waitSeconds=120
Content-Type: application/json
accessToken: abcdefg123

{}

Response

{
  "result": true,
  "holdId": "3f9c1e0a7b2d4c5e8a1b6d9f0c2e4a71",
  "status": {
    "isPaused": true,
    "pauseId": "b41d7c2e90a64f13b5c8e7d2a1f06c93",
    "runningCount": 3,
    "pausedCount": 3,
    "allPaused": true,
    "pendingCount": 4,
    "duration": "00:30:00",
    "fullPauseAt": "2026-10-27T18:12:40Z",
    "resumeAt": "2026-10-27T18:42:40Z",
    "requestedAt": "2026-10-27T18:12:05Z",
    "requestedBy": "API (workspace Production, key Planning Analytics)",
    "holdId": "3f9c1e0a7b2d4c5e8a1b6d9f0c2e4a71",
    "holdCount": 1,
    "releasedHoldCount": null,
    "unpausableCount": 0,
    "message": "Paused until 14:42"
  }
}

A call that waits should be repeated, not made longer: if result is false, ask again with pause/status, or call pause again for another wait. Each pause call adds a hold, so release the earlier one with its holdId.

Pause status#

Returns the current state of the pause. Poll it to see how many jobs have paused.

GET https://localhost:8600/api/v1/pause/status?accessToken=abcdefg123

The response is the status object:

{
  "isPaused": true,
  "pauseId": "b41d7c2e90a64f13b5c8e7d2a1f06c93",
  "runningCount": 17,
  "pausedCount": 12,
  "allPaused": false,
  "pendingCount": 4,
  "duration": null,
  "fullPauseAt": null,
  "resumeAt": null,
  "requestedAt": "2026-10-27T18:12:05Z",
  "requestedBy": "API (workspace Production, key Planning Analytics)",
  "holdId": null,
  "holdCount": 1,
  "releasedHoldCount": null,
  "unpausableCount": 0,
  "message": "12 of 17 running jobs paused"
}
Field Meaning
isPaused true while at least one pause is active.
pauseId Identifies the current pause as a whole.
runningCount, pausedCount Running jobs, and how many of them are paused.
allPaused true when every running job is paused and the system has had a few seconds to settle. This is the "safe to proceed" signal.
pendingCount Jobs waiting in the queue.
duration The length of the most recent timed pause as hours, minutes and seconds, or null when it lasts until a resume.
fullPauseAt When every running job became paused (UTC), or null if that has not happened yet.
resumeAt For a timed pause, when it ends (UTC). null until every job is paused, and for a pause that lasts until a resume.
requestedAt, requestedBy When the pause was requested (UTC) and by whom. For a call over the API, requestedBy names the workspace and the Local API key.
holdId Set only in the response to a pause command: the pause that call added.
holdCount How many pauses (holds) are active.
releasedHoldCount Set only in the response to a resume command: how many holds it released.
unpausableCount Running jobs that run inside the web app and cannot pause.
message The text the Activity screen shows, for example All jobs paused, safe to proceed or Not paused.

Resume#

Ends a pause and lets queued jobs start and paused jobs carry on.

Parameter Meaning
holdId The holdId from a pause response. Releases only that pause. Reportworq stays paused while another pause is active. An unknown or already ended holdId answers 404.

Without holdId, the command is an all-clear: it releases every pause, whoever made it, including one set from the Activity screen and one made with another workspace's access token. It does the same as Resume jobs on the Activity screen. Pass holdId when you want to release only your own pause.

POST https://localhost:8600/api/v1/resume?holdId=3f9c1e0a7b2d4c5e8a1b6d9f0c2e4a71
Content-Type: application/json
accessToken: abcdefg123

{}

The response is the status object after the release:

{
  "isPaused": false,
  "pauseId": null,
  "runningCount": 3,
  "pausedCount": 0,
  "allPaused": false,
  "pendingCount": 4,
  "duration": null,
  "fullPauseAt": null,
  "resumeAt": null,
  "requestedAt": null,
  "requestedBy": null,
  "holdId": null,
  "holdCount": 0,
  "releasedHoldCount": 1,
  "unpausableCount": 0,
  "message": "Not paused"
}

A call without holdId while Reportworq is not paused succeeds and releases nothing: releasedHoldCount is 0.

Cancel all#

Cancels the running jobs, and with a parameter the queued jobs, of the workspace that the access token belongs to. It does not affect other workspaces and it does not start or end a pause.

Parameter Meaning
includePending true to cancel the jobs waiting in the queue as well. Default false.
pendingOnly true to cancel only the jobs waiting in the queue. Running jobs, and jobs held by a pause, carry on. Default false.

A value other than true or false for either parameter answers 400 with a message that names the parameter. Use pendingOnly=true during a pause to clear the backlog and let the work in flight finish.

POST https://localhost:8600/api/v1/cancelall?includePending=true
Content-Type: application/json
accessToken: abcdefg123

{}
{
  "runningCancelled": 2,
  "pendingCancelled": 4,
  "executionIds": [
    "f943029d31564dd8b2bd59f6b25706fc",
    "0a7e51c3d98b4e6f9b2d14c6a8e03f57"
  ]
}

To cancel the queue only, send POST https://localhost:8600/api/v1/cancelall?pendingOnly=true. The answer has the same shape, with runningCancelled 0.

The Cancel all menu on the Activity screen is wider: it cancels across every workspace.

Tell a waiting job from a stuck one#

A Turbo Integrator process or script that runs a job with run and then polls status can see that the job is waiting on a pause rather than stuck. During a pause, run still returns HTTP 200 and queues the job, with isPaused: true in the reply. status returns isPaused: true and a pauseMessage while the job is queued behind the pause (Pending (paused by an administrator), "Jobs are paused by an administrator. It will start after the resume.") or held by it (Paused - N of M tasks completed, "Jobs are paused by an administrator. It will continue after the resume."). A running job that has not reached a safe point yet still reads as running, with isPaused: false. So test isPaused before you treat a long wait as a failure, and keep polling until the resume. The exact replies are on Run a job by API.

Notes and limits#

Going deeper. For the two delivery models of the API and the Cloud API's key model, read The automation API. To run and monitor a job, see Run a job by API.

Feedback on this page

Comments, questions, requests, or something missing or unclear? Email us - the page you are on is filled in for you.

Email feedback on this page

Or write to support@reportworq.com directly.