Suspend an automation run

automation.run.suspend@1

Pauses a run at its next safe stopping point, keeping what it has finished so far. Resume continues it. It needs a key with Automations control.

Pause a run

Replace YOUR_FEATURE_ID with the featureId this operation's catalogue entry gives, and YOUR_RUN_REF with a run's runRef from Find automation runs. expectedRevision is the run's revision.

# A new operationId for each new request; the same one to retry it.
curl https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations \
  -H "Authorization: Bearer gl_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "target": {
    "featureId": "YOUR_FEATURE_ID",
    "export": "suspendRun",
    "contractRef": "automation.run.suspend@1"
  },
  "operationId": "suspend-run-1",
  "input": {
    "runRef": "YOUR_RUN_REF",
    "expectedRevision": 3
  }
}'

// A new operationId for each new request; the same one to retry it.
const response = await fetch(
  "https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer gl_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "target": {
        "featureId": "YOUR_FEATURE_ID",
        "export": "suspendRun",
        "contractRef": "automation.run.suspend@1"
      },
      "operationId": "suspend-run-1",
      "input": {
        "runRef": "YOUR_RUN_REF",
        "expectedRevision": 3
      }
    }),
  },
);
const receipt = await response.json();
console.log(response.status, receipt);

import requests

# A new operationId for each new request; the same one to retry it.
response = requests.post(
    "https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations",
    headers={"Authorization": "Bearer gl_YOUR_API_KEY"},
    json={
        "target": {
            "featureId": "YOUR_FEATURE_ID",
            "export": "suspendRun",
            "contractRef": "automation.run.suspend@1",
        },
        "operationId": "suspend-run-1",
        "input": {
            "runRef": "YOUR_RUN_REF",
            "expectedRevision": 3,
        },
    },
    timeout=30,
)
print(response.status_code, response.json())

Parameters

What goes in input:

Name Type Required Description
runRef string Yes The run to change: its runRef from Find automation runs.
expectedRevision integer Yes The run's revision when you read it (Automation run inspector). If the run has changed since, nothing is done and the answer is a conflict.

Response

A call that worked answers 200 with an applied receipt; its output holds these fields. GET /catalog/automation.run.suspend@1 answers the complete shape as JSON Schema.

Name Type Description
runRef string The run.
revision integer The run's new revision.
state one of preparing, queued, running, waiting, needs-input, suspended, succeeded, completed-with-errors, failed, uncertain, cancelled Where the run is now: preparing, queued, running, waiting, needs-input, suspended, succeeded, completed-with-errors, failed, uncertain or cancelled. 
{
  "status": "applied",
  "operationId": "suspend-run-1",
  "output": {
    "runRef": "11111111-2222-4333-8444-555555555555",
    "revision": 4,
    "state": "suspended"
  }
}

Errors

Besides the answers every request can get (Errors), its receipt can say:

Status HTTP What it means
pending 202 Accepted and still running. Look it up with GET /operations/{operationId}.
uncertain 202 GrowLocal can't yet tell whether it took effect. Look it up before trying again.
requirements 409 Something must happen first; the receipt lists what.
conflict 409 The row changed since you read it, or this operationId was used with a different body.
rejected 400, or 403 when it's a matter of access Not done. diagnostics says why: each has a code, a path into what you sent and a message.

The codes in diagnostics you're most likely to see:

Code Status What it means
AUTOMATION.REVISION_CONFLICT conflict The run is at another revision than expectedRevision. Read it again.
AUTOMATION.RUN_NOT_FOUND rejected No such run here for this key.
AUTOMATION.CONTROL_NOT_APPLICABLE conflict The run is not in a state that can be paused (it has finished or is already paused).
AUTOMATION.OPERATION_REPLAY_MISMATCH conflict This operationId was already used with a different body. Use a new one.
AUTOMATION.FEATURE_DISABLED rejected That feature is switched off for this business.
AUTOMATION.SOURCE_DISABLED rejected The automation the run belongs to is switched off.