Run a schedule now

POST

/v1/schedules/{triggerId}/run-now

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

• Same-origin — path relative to the deployment root.

One fire outside the schedule (manual: true in its history), starting one run as the schedule’s owner. The schedule’s next occurrence is unchanged. A personal schedule’s owner or a project admin fires 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 workspace 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). A request whose key store can’t be read before it runs is answered 503 idempotency-store-unavailable with Retry-After: nothing ran, so retry with the same key (from 0.3.0).

Responses

202

The fire; its run starts in the background.

Media typeapplication/json

One fire of a schedule (an occurrence, or a run-now) and what came of it. pending while its run is being started.

object

fireId

required

string

scheduleId

required

string

triggerId

required

string

scheduledFor

The occurrence it is for; absent on a run-now fire.

string format: date-time

firedAt

required

string format: date-time

outcome

required

skipped-overlap: the previous fire’s run was still going (overlap: skip). skipped-erasure: the person the fire acts for is being erased, so no new run starts for them until the erasure completes. skipped, as detail says: what an improve schedule waits for wasn’t there (enough new corrections since its last Improve run, or room under its month’s cap); the target’s project is suspended (project-suspended), so no run or Improve run started; its run or Improve run hadn’t started when its workspace was suspended, and the restore concluded it (tenant-suspended); or its workspace was suspended or closing as its run started (tenant-suspended, tenant-closing). None of the skipped outcomes counts toward the auto-pause; refused and failed do, unless countsTowardPause is false. A skip for a suspension or a close (project-suspended, tenant-suspended, tenant-closing) doesn’t reset the auto-pause’s count of fires in a row either.

string

Allowed values: pending started skipped-overlap skipped-erasure skipped refused failed

runId

The run it started.

string format: uuid

version

The trigger’s version its run started with: the newest when it started. Absent until the run starts.

integer

>= 1

improveRunId

The Improve run it started (an improve schedule).

string format: uuid

detail

Why it was refused, skipped or failed.

string

countsTowardPause

Whether this fire counted toward the trigger’s auto-pause (5 in a row by default). false for a refusal for a limit, such as the workspace’s runs pending (detail starts rate-limited:): the limit passes, and the trigger isn’t at fault. Absent from a runtime that doesn’t say: refused and failed fires counted, and the others didn’t.

boolean

missedCount

Occurrences this fire stood in for after a gap (catchUp: latest).

integer

>= 1

manual

A run-now fire, outside the schedule.

boolean

Example

{
  "outcome": "pending"
}

400

Malformed request body.

Media typeapplication/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.

Media typeapplication/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 (for an improve schedule, publish on the agent) is refused first, and learns nothing of its owner.

Media typeapplication/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.

Media typeapplication/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.

Media typeapplication/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).

Media typeapplication/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"
  }
}

501

trigger-operation-unsupported: this deployment has no run-now.

Media typeapplication/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"
  }
}

503

The Idempotency-Key store couldn’t be read before the request ran (idempotency-store-unavailable), so nothing was changed; Retry-After (whole seconds) says when to try again with the same key.

Media typeapplication/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"
  }
}

See also

• GET /v1/schedules/{triggerId}: Fetch a cron schedule
• PATCH /v1/schedules/{triggerId}: Update a cron schedule
• POST /v1/schedules/{triggerId}/pause: Pause a cron schedule
• POST /v1/schedules/{triggerId}/resume: Resume a cron schedule
• Error code idempotency-store-unavailable
• Error code permission-denied
• Error code trigger-operation-unsupported
• Every error code