Skip to content
Kindgi

Run a schedule now

View as Markdown
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>'

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.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
triggerId
required
string format: uuid

TriggerId — the trigger id (a UUID).

Header Parameters

Section titled “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

Section titled “Responses”

202

Section titled “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 (its threshold, or its monthly cap); the target’s project is suspended (project-suspended), so no run or pass started; its run or pass hadn’t started when its tenant was suspended, and the restore concluded it (tenant-suspended); or its tenant 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
passId

The improvement pass 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 tenant’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

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

501

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also