run_schedule #
On this page
Generated automatically from the published contract sources.
A script calls this action over HTTPS at POST https://tzcloud.turnzero.ai/v1/run_schedule, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool tzcloud_run_schedule.
OAuth access tokens and minted tokens, including the turnzero command's computer token, are bearer credentials. The action determines which kinds, scopes and grants it accepts (Sign-in, sessions, and tokens).
Build metadata: Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.
Contract description #
Start one declared schedule now as a manual run. You get running at once. Read its result with read_schedules. Deploy or promote after declaring it, or get schedule_not_deployed. Resume a halted environment first (target_environment_halted). Each call is metered. A run is one backend action. It refuses run_in_flight while the schedule's last run is running. A manual run leaves the timetable and next_due unchanged. A retry checks the gates again. The same request_id returns the same run. wait_seconds waits for it to end. The account owner must have requested or agreed to this production run. Development needs no ask.
An answer not from this platform, such as a gateway error page or closed connection, gives no start outcome. First call read_schedules. Repeat only with the same request_id: it returns the first run or starts one if none started.
woke is true if the run woke the app, false if already running, or null (unknown, no action).
More about this action #
The call is refused schedule_not_deployed until the environment has a deploy or promote made since the schedule was declared. For production, the deploy or promote a schedule needs is the deploy on an application with one environment, and the promote on an application with two.
While the run is still running, next gives the read_schedules call that waits for it. Once the run has settled, the answer also contains the run's console lines in console, at most 40, and more gives the read_logs call for any lines it left out.
The request_id argument: after the call checks the requested schedule and whether its deployment allows a run, a repeated value returns the earlier run, even if that run belongs to another schedule or environment.
The wait_seconds argument: the seconds, 1 to 45, that the call waits for the run it returns to end before it replies. That run is the one it started, or the one a repeated request_id identifies. The platform reads the run every two seconds and stops once this many seconds have passed since the call arrived, then replies with settled and waited_ms. Left out, the call returns at once, with a run it started in the state running. Each server holds one wait per application. This call's wait takes that place. A concurrent held read_status or read_schedules for that application on the same server returns at once, from its own read. A value outside that range is refused invalid_request, and its detail gives 45 as the bound.
The due_at argument: an instant in UTC on a whole minute, at or before the call, such as 2026-09-07T03:00:00Z, that the schedule's own cron expression yields. The run is due at that instant, and its handler receives it as a scheduled run at that instant would, so you can test the handler at that point in the timetable. The schedule's next_due still does not move. An instant still to come, one the expression does not yield, or one older than the run records' retention is refused invalid_request, and its detail says why.
A halted environment is refused target_environment_halted; call halt_environment with resume: true first. Each call is a metered management action; a run is one backend action. The requested schedule and deployment gates are checked again before a repeated request_id returns its earlier run.
Access and action metadata #
{
"name": "run_schedule",
"resource": "application",
"tier": "reversible",
"surface": "tzcloud",
"addresses": [
"tzcloud"
],
"product": "cloud",
"clients": [
"bearer",
"browser_session"
],
"summary": "Fire one declared schedule now as a manual run: it returns `running` at once, and you read the run back through `read_schedules`. It is refused `run_in_flight` while the schedule's last run is still running. It is refused `schedule_not_deployed` until the environment has a deploy or promote made since the schedule was declared: for production, the deploy on one environment and the promote on two. A retry with the same `request_id` returns the same run. It is refused `target_environment_halted` too, where the environment is halted. With `wait_seconds` (1 to 45), the answer is held until the run ends, and it carries `settled` and `waited_ms`. With or without the wait, it carries `next` while the run is still running. Settled, it also carries the run's console lines in `console`, at most 40, with `more` giving the `read_logs` call for any it left out.\n\nAn answer that is not this platform's own, such as a gateway's error page or a closed connection, says nothing about whether the run started. Read `read_schedules` first, and repeat the call only with the same `request_id`, which returns the run the first call started, or starts it where the first call did not.",
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"openWorldHint": true
}
}
MCP catalog entry #
{
"name": "run_schedule",
"title": "Run a scheduled job now",
"tier": "reversible",
"scenario": "CHI-L0-09",
"summary": "Start one declared schedule now as a manual run. You get `running` at once. Read its result with `read_schedules`. Deploy or promote after declaring it, or get `schedule_not_deployed`. Resume a halted environment first (`target_environment_halted`). Each call is metered. A run is one backend action. It refuses `run_in_flight` while the schedule's last run is running. A manual run leaves the timetable and `next_due` unchanged. A retry checks the gates again. The same `request_id` returns the same run. `wait_seconds` waits for it to end. The account owner must have requested or agreed to this production run. Development needs no ask.\n\nAn answer not from this platform, such as a gateway error page or closed connection, gives no start outcome. First call `read_schedules`. Repeat only with the same `request_id`: it returns the first run or starts one if none started.\n\n`woke` is `true` if the run woke the app, `false` if already running, or `null` (unknown, no action).",
"owners": [
"SVC-L0-15",
"MAPI-04"
]
}
request #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["application","schedule","request_id"] |
| / |
Your account's application id from list_applications, not its name or label.Type: string |
| / |
The nonempty name of a schedule declared for the environment; until a deploy or promote since its declaration carries it, the run is refused schedule_not_deployed.Type: string |
| / |
development or production, production if absent or empty; development on one environment draws environment_not_created.Type: string |
| / |
A nonempty id for this request, reused only to retry it, since a repeated value returns the earlier run of any schedule or environment of the application. Type: string |
| / |
Seconds to hold the answer until the run this call returns ends; a value out of range is refused invalid_request.Type: integer Minimum: 1 Maximum: 45 |
| / |
UTC instant in RFC 3339 at a whole minute the schedule's cron yields, at or before this call and within run-record retention. It is the run's due instant. The run is manual. Its trigger is manual. Other values are refused invalid_request, saying why.Type: string |
response #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Without wait_seconds, returned at once with the run as the start read it, running for a run this call started, its end read through read_schedules, the call next carries while the run is running. With wait_seconds, the answer is held until the run ends: settled, it carries the run's outcome and its console lines in console; unsettled, it carries next. Every answer is 200.Type: object Required fields: ["contract_version","run"] |
| / |
Required value: 1 |
| / |
The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call. Type: string Pattern: ^[0-9a-f]{10}$ |
| / |
The run this call started, or the run a repeated request_id identifies. With wait_seconds, it is the run as the one read after the wait found it, its outcome read there, or, where that read failed or did not complete in time, as the start read it, and settled is false then.Type: object Required fields: ["id","schedule","environment","trigger","due","started_at","ended_at","outcome","status","duration_ms","detail","woke"] |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string Allowed values: ["schedule","manual"] |
| / |
the due instant in UTC (ISO 8601) Type: string |
| / |
Type: ["string","null"] |
| / |
Type: ["string","null"] |
| / |
Type: string Allowed values: ["running","succeeded","failed","window_ended","unreachable","skipped","missed","abandoned"] |
| / |
the handler's HTTP status where it responded Type: ["integer","null"] |
| / |
Type: ["integer","null"] |
| / |
Type: ["string","null"] |
| / |
true where the fire found the compute at zero, false where it was running; null if the read failed, a start was under way, on the container grain, or while running. A null means the platform could not tell whether this run woke the application. The run's outcome does not depend on that read; nothing needs doing for the null. Type: ["boolean","null"] |
| / |
Present where the request carried wait_seconds. True where the one read after the wait found the run this call returns ended, whatever ended the wait, and run carries its outcome. False means that read found the run still running, or could not read it in time and run is the run as the start read it, and not that the run failed: next gives the call that waits on it.Type: boolean |
| / |
Present where the request carried wait_seconds: the milliseconds the answer was held before its read of the run.Type: integer Minimum: 0 |
| / |
Present while the run this answer returns is running: at once without wait_seconds, and where the wait did not settle. It is the exact call that reads the run to its end, read_schedules for the run's environment, with wait_seconds 45.Type: object Required fields: ["action","arguments"] Additional properties: false |
| / |
Required value: read_schedules |
| / |
Type: object Required fields: ["application","environment","wait_seconds"] Additional properties: false |
| / |
Type: string |
| / |
Type: string Allowed values: ["development","production"] |
| / |
Required value: 45 |
| / |
Present where settled is true: the console lines the run's environment wrote from one second before the run's start to one second after its end, read as read_logs reads its container source. The lines are the process's, so a request served during the run can add its own. The lines member holds the newest, oldest first, in read_logs' <time> <stream> <text> form, at most 40 of at most 512 bytes and 4,096 bytes in all. A true truncated says a bound cut or left out a line, and a true ingesting that lines may still be in the ingestion. An outcome of empty says no line was kept, and unavailable, with no lines, that the read failed, ran past its bound, or was not made: at shutdown, or where the environment has no compute. Where truncated or ingesting is true or the read is unavailable, more is the read_logs call that reads the console on from the window's start, up to 1,000 lines.Type: object Required fields: ["outcome","lines","truncated","ingesting"] Additional properties: false |
| / |
Type: string Allowed values: ["lines","empty","unavailable"] |
| / |
Type: array |
| / |
Type: string |
| / |
Type: boolean |
| / |
Type: boolean |
| / |
Type: object Required fields: ["action","arguments"] Additional properties: false |
| / |
Required value: read_logs |
| / |
Type: object Required fields: ["application","environment","source","since","limit"] Additional properties: false |
| / |
Type: string |
| / |
Type: string Allowed values: ["development","production"] |
| / |
Required value: container |
| / |
Type: string |
| / |
Required value: 1000 |
| / |
Without due_at, says this manual run checks the handler; read read_schedules after next_due for a run with trigger: "schedule". Without wait_seconds, identifies both waits by their actions: run_schedule's own, which holds this answer until the run ends, and read_schedules', which holds its answer until no run of the environment is in flight. With it, states how the run ended, that console holds its lines where the read kept any, and the read_logs call that reads them; or the next call where it is still running.Type: string |
Complete payload contract #
{
"request": {
"type": "object",
"required": [
"application",
"schedule",
"request_id"
],
"properties": {
"application": {
"type": "string",
"description": "Your account's application `id` from `list_applications`, not its name or label."
},
"schedule": {
"type": "string",
"description": "The nonempty name of a schedule declared for the environment; until a deploy or promote since its declaration carries it, the run is refused `schedule_not_deployed`."
},
"environment": {
"type": "string",
"description": "`development` or `production`, production if absent or empty; development on one environment draws `environment_not_created`."
},
"request_id": {
"type": "string",
"description": "A nonempty id for this request, reused only to retry it, since a repeated value returns the earlier run of any schedule or environment of the application."
},
"wait_seconds": {
"type": "integer",
"minimum": 1,
"maximum": 45,
"description": "Seconds to hold the answer until the run this call returns ends; a value out of range is refused `invalid_request`."
},
"due_at": {
"type": "string",
"description": "UTC instant in RFC 3339 at a whole minute the schedule's cron yields, at or before this call and within run-record retention. It is the run's due instant. The run is manual. Its `trigger` is `manual`. Other values are refused `invalid_request`, saying why."
}
}
},
"response": {
"type": "object",
"required": [
"contract_version",
"run"
],
"properties": {
"contract_version": {
"const": 1
},
"reference": {
"type": "string",
"pattern": "^[0-9a-f]{10}$",
"description": "The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call."
},
"run": {
"type": "object",
"description": "The run this call started, or the run a repeated `request_id` identifies. With `wait_seconds`, it is the run as the one read after the wait found it, its outcome read there, or, where that read failed or did not complete in time, as the start read it, and `settled` is false then.",
"required": [
"id",
"schedule",
"environment",
"trigger",
"due",
"started_at",
"ended_at",
"outcome",
"status",
"duration_ms",
"detail",
"woke"
],
"properties": {
"id": {
"type": "string"
},
"schedule": {
"type": "string"
},
"environment": {
"type": "string"
},
"trigger": {
"type": "string",
"enum": [
"schedule",
"manual"
]
},
"due": {
"type": "string",
"description": "the due instant in UTC (ISO 8601)"
},
"started_at": {
"type": [
"string",
"null"
]
},
"ended_at": {
"type": [
"string",
"null"
]
},
"outcome": {
"type": "string",
"enum": [
"running",
"succeeded",
"failed",
"window_ended",
"unreachable",
"skipped",
"missed",
"abandoned"
]
},
"status": {
"type": [
"integer",
"null"
],
"description": "the handler's HTTP status where it responded"
},
"duration_ms": {
"type": [
"integer",
"null"
]
},
"detail": {
"type": [
"string",
"null"
]
},
"woke": {
"type": [
"boolean",
"null"
],
"description": "true where the fire found the compute at zero, false where it was running; null if the read failed, a start was under way, on the container grain, or while running. A null means the platform could not tell whether this run woke the application. The run's outcome does not depend on that read; nothing needs doing for the null."
}
}
},
"settled": {
"type": "boolean",
"description": "Present where the request carried `wait_seconds`. True where the one read after the wait found the run this call returns ended, whatever ended the wait, and `run` carries its outcome. False means that read found the run still `running`, or could not read it in time and `run` is the run as the start read it, and not that the run failed: `next` gives the call that waits on it (MAPI-04; SCH-L0-06)."
},
"waited_ms": {
"type": "integer",
"minimum": 0,
"description": "Present where the request carried `wait_seconds`: the milliseconds the answer was held before its read of the run."
},
"next": {
"type": "object",
"required": [
"action",
"arguments"
],
"properties": {
"action": {
"const": "read_schedules"
},
"arguments": {
"type": "object",
"required": [
"application",
"environment",
"wait_seconds"
],
"properties": {
"application": {
"type": "string"
},
"environment": {
"type": "string",
"enum": [
"development",
"production"
]
},
"wait_seconds": {
"const": 45
}
},
"additionalProperties": false
}
},
"additionalProperties": false,
"description": "Present while the run this answer returns is `running`: at once without `wait_seconds`, and where the wait did not settle. It is the exact call that reads the run to its end, `read_schedules` for the run's environment, with `wait_seconds` 45."
},
"console": {
"type": "object",
"required": [
"outcome",
"lines",
"truncated",
"ingesting"
],
"properties": {
"outcome": {
"type": "string",
"enum": [
"lines",
"empty",
"unavailable"
]
},
"lines": {
"type": "array",
"items": {
"type": "string"
}
},
"truncated": {
"type": "boolean"
},
"ingesting": {
"type": "boolean"
},
"more": {
"type": "object",
"required": [
"action",
"arguments"
],
"properties": {
"action": {
"const": "read_logs"
},
"arguments": {
"type": "object",
"required": [
"application",
"environment",
"source",
"since",
"limit"
],
"properties": {
"application": {
"type": "string"
},
"environment": {
"type": "string",
"enum": [
"development",
"production"
]
},
"source": {
"const": "container"
},
"since": {
"type": "string"
},
"limit": {
"const": 1000
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"additionalProperties": false,
"description": "Present where `settled` is true: the console lines the run's environment wrote from one second before the run's start to one second after its end, read as `read_logs` reads its `container` source. The lines are the process's, so a request served during the run can add its own. The `lines` member holds the newest, oldest first, in `read_logs`' `<time> <stream> <text>` form, at most 40 of at most 512 bytes and 4,096 bytes in all. A true `truncated` says a bound cut or left out a line, and a true `ingesting` that lines may still be in the ingestion. An `outcome` of `empty` says no line was kept, and `unavailable`, with no lines, that the read failed, ran past its bound, or was not made: at shutdown, or where the environment has no compute. Where `truncated` or `ingesting` is true or the read is unavailable, `more` is the `read_logs` call that reads the console on from the window's start, up to 1,000 lines (SCH-L0-06)."
},
"detail": {
"type": "string",
"description": "Without `due_at`, says this manual run checks the handler; read `read_schedules` after `next_due` for a run with `trigger: \"schedule\"`. Without `wait_seconds`, identifies both waits by their actions: `run_schedule`'s own, which holds this answer until the run ends, and `read_schedules`', which holds its answer until no run of the environment is in flight (MAPI-04). With it, states how the run ended, that `console` holds its lines where the read kept any, and the `read_logs` call that reads them; or the `next` call where it is still running."
}
},
"description": "Without `wait_seconds`, returned at once with the run as the start read it, `running` for a run this call started, its end read through `read_schedules`, the call `next` carries while the run is running (SCH-L0-06). With `wait_seconds`, the answer is held until the run ends: settled, it carries the run's outcome and its console lines in `console`; unsettled, it carries `next` (MAPI-04; SCH-L0-06). Every answer is 200."
}
}
Shared contracts #
- Refusals: every refusal, by surface, with its cause and its remedy
- schemas/wire_error.schema.json
- schemas/wire_errors.json
- schemas/action_payloads.json (includes shared shapes)
- management_api_contract.md