# Run a schedule now POST /v1/schedules/{triggerId}/run-now ```sh curl --request POST \ --url https://example.com/v1/schedules/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/run-now \ --header 'Authorization: Bearer ' ``` 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](https://docs.kindgi.com/v0.5.0/reference/api.md#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. application/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 ```json { "outcome": "pending" } ``` ### 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 ##### Examplegenerated ```json { "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 ##### Examplegenerated ```json { "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. 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 ##### Examplegenerated ```json { "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 ##### Examplegenerated ```json { "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 ##### Examplegenerated ```json { "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 ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ### 501 `trigger-operation-unsupported`: this deployment has no run-now. 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 ##### Examplegenerated ```json { "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. 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 ##### Examplegenerated ```json { "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" } } ``` ## See also - [`GET /v1/schedules/{triggerId}`: Fetch a cron schedule](https://docs.kindgi.com/v0.5.0/reference/api/operations/schedulesget.md) - [`PATCH /v1/schedules/{triggerId}`: Update a cron schedule](https://docs.kindgi.com/v0.5.0/reference/api/operations/schedulesupdate.md) - [`POST /v1/schedules/{triggerId}/pause`: Pause a cron schedule](https://docs.kindgi.com/v0.5.0/reference/api/operations/schedulespause.md) - [`POST /v1/schedules/{triggerId}/resume`: Resume a cron schedule](https://docs.kindgi.com/v0.5.0/reference/api/operations/schedulesresume.md) - [Error code `idempotency-store-unavailable`](https://docs.kindgi.com/v0.5.0/reference/errors.md#idempotency-store-unavailable) - [Error code `permission-denied`](https://docs.kindgi.com/v0.5.0/reference/errors.md#permission-denied) - [Error code `trigger-operation-unsupported`](https://docs.kindgi.com/v0.5.0/reference/errors.md#trigger-operation-unsupported) - [Every error code](https://docs.kindgi.com/v0.5.0/reference/errors.md)