Skip to content

List scheduled actions

GET
/admin/scheduled-actions

Lists the actions scheduled on this instance, newest first: what is still waiting to run, and what has already run, failed or been cancelled. Posts that their authors scheduled to publish are included.

Right now the only part of the app that creates actions is an author scheduling a post, and there’s no endpoint for creating any other kind. The response doesn’t say where an action came from. A pending action becomes due at its scheduled_for time. A background job normally checks for due actions about every five minutes, but that isn’t a deadline: a backlog, a failed job run, or a server that was down or busy can delay an action. The server also tries to record each run or failure in the audit log as scheduled_action.executed or scheduled_action.failed, but an entry can be missing.

The list is ordered by when each action was created. Pass next_cursor back as cursor to get the next page. The cursor holds only a creation time, so actions created at exactly the same moment can be skipped at a page boundary. If the last page happens to be exactly full, it still has a next_cursor, which leads to an empty page.

You need system.admin.

state
string
Allowed values: pending done cancelled failed

Only actions in this state. Any other value, including an empty one, returns no actions.

limit
integer
default: 50 >= 1 <= 200

Use a value from 1 to 200. Other values aren’t rejected, but the response may then leave out next_cursor even when there are more actions.

cursor
string

The next_cursor from the previous page. A cursor the server can’t read is ignored, and you get the first page.

A page of scheduled actions, most recently created first.

object
items
required
Array<object>

One scheduled action: an instruction to act on a target once scheduled_for has passed. The row stays after the action runs, fails or is cancelled.

object
id
required
string format: uuid
action
required

What to do. restrict and change_sensitivity change an asset’s sensitivity (restrict sets it to restricted); delete soft-deletes an asset; change_state moves an asset to another workflow state, or publishes or unpublishes a post; notify sends a notification about any kind of target.

string
Allowed values: restrict delete change_state change_sensitivity notify
target_kind
required
string
Allowed values: asset post collection user
target_id
required

The target’s id as text: a UUID for an asset, post or collection, or a user ref for a user.

string
params

Settings for the action. They’re only checked when it runs, so a mistake shows up as a failed action. change_sensitivity takes to (public, team, restricted or embargo); change_state takes a state code in to_state (for a post, published or wip) or a state id in to_state_id; delete takes an optional reason; notify takes recipient (a user ref, required unless the target is a user), verb and reason.

object
key
additional properties
any
scheduled_for
required

When the action becomes due. It never runs before this time, and it can run some time after it.

string format: date-time
state
required

pending until the action runs, then done or failed; cancelled if it was cancelled first. done can also mean nothing needed changing, for example a post that was already published.

string
Allowed values: pending done cancelled failed
error

Why the action failed. Only present when state is failed.

string
nullable
created_by

The user who scheduled the action. Left out when no user is behind it.

integer format: int64
nullable
created_at
required

When the action was scheduled. The list is ordered by this, not by scheduled_for.

string format: date-time
executed_at

When the action ran, whether it succeeded or failed. Left out while it’s pending and for cancelled actions.

string format: date-time
nullable
next_cursor

Pass this as cursor to get the next page. Left out when the page has fewer actions than limit.

string
nullable

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed