Pause a cron schedule

POST

/v1/schedules/{triggerId}/pause

const url = 'https://example.com/v1/schedules/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/pause';
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/v1/schedules/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/pause \
  --header 'Authorization: Bearer <token>'

Idempotent-per-state: pausing an already-paused row returns 409 trigger-already-in-state. A personal schedule’s owner or a project admin pauses it; a shared one, any writer of its project.

Authorizations

bearerAuth

Parameters

Path Parameters

triggerId

required

string format: uuid

TriggerId — the trigger id (a UUID).

Header Parameters

Idempotency-Key

string

>= 1 characters

Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5).

Responses

200

Paused schedule.

application/json

A schedule: what it runs (a flow at a version, or an agent), when (a cron expression in a timezone), as whom (its owner), and what it does after a gap or while a run is still going.

object

scheduleId

required

Domain-friendly alias for triggerId — the trigger id (a UUID). Use interchangeably in admin URLs.

string

triggerId

required

string

flowId

A schedule that runs a flow: the flow, at flowVersion.

string

>= 1 characters

flowVersion

string

>= 1 characters

agentId

A schedule that runs an agent: the agent, at agentVersion, else its version live for the schedule’s project (else the latest), as a run that names none.

string

>= 1 characters

agentVersion

string

>= 1 characters

improve

A schedule that starts Improve runs: on this agent, for this scope, when enough answers have been marked wrong since its last Improve run (input: the threshold, the monthly cap and the Improve options).

object

agentId

required

string

>= 1 characters

scope

required

One of: discriminator: kind

The agent’s default for the whole tenant.

object

kind

required

string

Allowed values: tenant

A segment path within a project: it covers every run whose path starts with it.

object

kind

required

string

Allowed values: segment

projectId

required

string format: uuid

path

required

Array<object>

>= 1 items <= 8 items

object

key

required

Lowercase, like an identifier: company, contact-role.

string

/^[a-z][a-z0-9_-]{0,63}$/

value

required

string

>= 1 characters <= 256 characters

projectId

The schedule’s project: its runs are this project’s.

string format: uuid

owner

Who its runs act as. A person: a personal trigger, which only they or a project admin change. A service account: a shared trigger. Only a take-over (POST …/owner) changes it. Checked again at every fire.

object

kind

required

string

Allowed values: user service

required

string

displayName

The owner’s name at the time of the response: the person’s display name, or the service account’s name. Absent when it can’t be read (no directory, a removed account) and from a runtime before Kindgi 0.1.6: show the id then.

string

isProjectAccount

Set when the owner is the trigger’s project’s own service account (runAsProject): the trigger is shared, and runs as the project. Show it as “This project”. Absent otherwise.

boolean

cronExpression

required

5- or 6-field cron expression (croner-compatible). 6-field enables second precision.

string

>= 1 characters

timezone

IANA timezone (e.g. UTC, America/New_York). Absent → UTC.

string

input

Static input handed to the run on every fire. Absent → {}.

catchUp

After a gap (the runtime was down, or a fire is later than startingDeadlineSeconds): latest runs once, for the latest missed occurrence, and its fire says how many it missed; skip drops the missed occurrences. Never a run per missed occurrence. A tenant’s suspension isn’t caught up either way: once the tenant is restored, a schedule that’s on fires next at its first occurrence after the restore.

string

Allowed values: latest skip

overlap

When an occurrence comes while the previous run of this schedule is still running: skip records the fire as skipped; allow starts another run.

string

Allowed values: skip allow

startingDeadlineSeconds

How late a fire may start and still count as on time; past it, catchUp applies.

integer

>= 1

label

required

string | null

status

required

Lifecycle status. Only active triggers fire. Tombstoned rows are excluded from every read path.

string

Allowed values: active paused

statusReason

Why the runtime paused it: repeated fires that were refused (the owner lost access) or failed. Skipped fires (an overlap, an erasure in progress) never count.

string

toolsAllowedUnattended

The tools whose calls in this schedule’s runs don’t wait for a person’s yes, though a tool asks for one in a run no person started (needsApprovalWhenUnattended). Absent: none. Each tool by its id, with no wildcard or pattern, and only tools this trigger’s flow or agent calls. It lifts only that wait: the tenant’s approval rules, the agent’s own rules, the permission check (as the trigger’s owner) and the tool’s own limits all still apply.

Array<string>

<= 100 items unique items

nextFireAt

required

Wall-clock time of the next scheduled fire. null on paused rows if the cron scheduler never re-armed.

string | null format: date-time

upcoming

The next occurrences, when the request asked for them (?upcoming=N).

Array<string>

lastFiredAt

required

string | null format: date-time

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

Example

{
  "improve": {
    "scope": {
      "kind": "tenant"
    }
  },
  "owner": {
    "kind": "user",
    "isProjectAccount": true
  },
  "catchUp": "latest",
  "overlap": "skip",
  "status": "active"
}

400

Malformed request body.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Missing / malformed / expired / revoked bearer token.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

403

permission-denied: the schedule is personal and the caller is neither its owner nor a project admin (the message names the owner), or it’s shared and changing what it runs takes a project admin. A caller without write on its project is refused first, and learns nothing of its owner.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

No cron trigger with that id.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Idempotency-Key was reused with a different body, or resource-state conflict.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Server error (unmapped domain code or framework crash).

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

Pause a cron schedule

Authorizations

Parameters

Path Parameters

Header Parameters

Responses

200

Example

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

404

Examplegenerated

409

Examplegenerated

500

Examplegenerated

See also

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated