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#
- The API entitlement must be on your license, or the command is refused with HTTP 400 and the message "REST API not available for this license".
- You need the access token of a Local API key (Settings, Configuration, API). The token goes in an
accessTokenheader, or in an?accessToken=query string. Any workspace's token may pause: a pause applies to the whole Reportworq server, whichever workspace the token belongs to. - A wrong, missing or disabled token answers 401.
- These commands are on the Local API only. The Cloud API relay does not carry them and answers "Invalid Command".
- Only the Reportworq web app answers these commands. A machine that only runs jobs answers 404.
- The address is
http(s)://{server}:{port}/api/v1/{command}. The default port is 8600, for examplehttps://localhost:8600/api/v1/pause.
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"
}
}
resultistruewhen every running job was paused within the wait,falsewhen the wait ran out first (the pause is still in force and the jobs are still pausing), andnullwhen you did not ask to wait.holdIdidentifies the pause this call added. Keep it to release only this pause with the resume command.statusis the same object that the pause status command returns.
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#
- Times are UTC in every field. Only the
messagetext shows the server's local time. - Every call is logged with the workspace and the key name of the token (the
pause/statuspoll is not). - Jobs that run inside the web app, writeback and contribution work, and interactive use of data sources from the web app are not paused. See Limits of the pause.
- For ready-made Turbo Integrator processes that make these calls, see Pause samples for Planning Analytics.
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 pageOr write to support@reportworq.com directly.