read_schedules #
On this page
Generated automatically from the published contract sources.
A script calls this action over HTTPS at POST https://tzcloud.turnzero.ai/v1/read_schedules, with a bearer credential and the action's payload as the JSON body. It also accepts GET. An MCP connection lists this action as the tool tzcloud_read_schedules.
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 #
Read an application's declared schedules for one environment. Use it after run_schedule or its lost answer, and read_logs for your run's output. The answer's halted says whether the environment is halted. Each schedule says whether its environment has a deploy or promote at or after its declaration. Production needs a deploy on one environment, and a promote on two. A one-environment application's development has no rows.
cron_preview holds up to three instants the cron yields. For a deployed row in an environment not halted, the platform claims them in turn. Within the tolerance, it runs the claimed due time and advances past other due times without running or recording them. A due time older than the tolerance produces one missed row with the count of due times passed over. deployed: false means no deploy or promote yet, or a declaration waiting for one. woke is true if the run woke the app, false if already running, or null (unknown, no action).
More about this action #
The wait_seconds argument: the seconds, 1 to 45, that the call waits until no run of the environment is in flight. The platform reads its store every two seconds and stops once this many seconds have passed since the call arrived. It then replies with settled and waited_ms.
Each schedule gives its next due time in UTC, its run in flight and last run, and its most recent runs with outcome, status and duration. The production act is the deploy on an application with one environment, and the promote on one with two.
To read one run's platform entry, call read_logs with source: "platform", field: "run" and value set to that run's id. The application's console lines have no run tag.
Access and action metadata #
{
"name": "read_schedules",
"resource": "application",
"tier": "observe",
"surface": "tzcloud",
"addresses": [
"tzcloud"
],
"product": "cloud",
"clients": [
"bearer",
"browser_session"
],
"summary": "An application's declared schedules for an environment. Each carries its next due time in UTC, the run in flight, the last run, and the most recent runs with outcome, status, and duration. Each also says whether the environment holds a deploy or promote made at or after the declaration: for production, the deploy on one environment and the promote on two. A declaration whose environment has none returns `deployed: false` with the reason: no deploy, or a declaration awaiting one. Each also carries `cron_preview`, up to three instants its cron yields; for a deployed row in an environment that is not halted, those are the due times the platform claims in turn, a claim late inside the tolerance passing due times over. With `wait_seconds` (1 to 45), the answer is held until no run of the environment is in flight, and it carries `settled` and `waited_ms`.",
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"openWorldHint": false,
"idempotentHint": true
}
}
MCP catalog entry #
{
"name": "read_schedules",
"title": "Read scheduled jobs",
"tier": "observe",
"scenario": "CHI-L0-09",
"summary": "Read an application's declared schedules for one environment. Use it after `run_schedule` or its lost answer, and `read_logs` for your run's output. The answer's `halted` says whether the environment is halted. Each schedule says whether its environment has a deploy or promote at or after its declaration. Production needs a deploy on one environment, and a promote on two. A one-environment application's development has no rows.\n\n`cron_preview` holds up to three instants the cron yields. For a deployed row in an environment not halted, the platform claims them in turn. Within the tolerance, it runs the claimed due time and advances past other due times without running or recording them. A due time older than the tolerance produces one `missed` row with the count of due times passed over. `deployed: false` means no deploy or promote yet, or a declaration waiting for one. `woke` is `true` if the run woke the app, `false` if already running, or `null` (unknown, no action).",
"owners": [
"PLD-L0-41",
"SVC-L0-15",
"PLD-L0-40",
"SCH-L0-06",
"MAPI-04"
]
}
request #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["application"] |
| / |
Your account's application id from list_applications, not its name or label.Type: string |
| / |
The environment, development or production, production by default; any other name draws invalid_request at its path.Type: string |
| / |
The most recent runs returned per schedule, 1 to 100, 5 by default. Type: integer Minimum: 1 Maximum: 100 |
| / |
Optional: seconds to hold the answer until no run of the environment read is in flight; absent, it returns at once. Out of range is refused invalid_request.Type: integer Minimum: 1 Maximum: 45 |
response #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","application","environment","halted","window_seconds","schedules"] |
| / |
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}$ |
| / |
Type: string |
| / |
Type: string |
| / |
False where the environment is running, never true; otherwise the halt's instant and author, during which no row of the environment is claimed and each row's next_due stays where it was.Type: ["object","boolean"] Required fields: ["at","by"] |
| / |
The instant the halt began, in UTC (ISO 8601). Type: string |
| / |
Who halted the environment: developer through halt_environment, or platform through the activity cap of the daily pass.Type: string Allowed values: ["developer","platform"] |
| / |
the schedule kind's bounded execution window, in seconds: a platform setting, the same for every application, so read_plan_quotas has no row for it, and the wake of a stopped environment by a due run counts against itType: integer |
| / |
The instant of this read, ISO 8601 in UTC, shared by every row's cron_preview. Compare a row's next_due or cron_preview with read_at to see whether that time has passed or how long remains.Type: string |
| / |
Type: array |
| / |
Type: object Required fields: ["name","cron","path","deployed","reason","next_due","in_flight","last_run","runs"] |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
whether the environment holds a deploy or promote made at or after the declaration Type: boolean |
| / |
set where deployed is false: the environment holds no version, or the declaration is newer than its last deploy Type: ["string","null"] Allowed values: ["no_deploy","awaiting_deploy",null] |
| / |
Type: ["string","null"] |
| / |
On every row: up to three instants the cron yields, in order, the first after read_at, each within 366 days of it. Where deployed is true and the answer's halted is false, the platform claims them in turn, and at each claim a run starts or its outcome is recorded. The outcome is skipped where another run is in flight, the account is suspended, or the router refuses the fire, and missed where the claim is late past the tolerance. A claim late inside it advances past a due time it did not take, which is neither run nor recorded. Before the deploy a row waits for, and during a halt, no instant is claimed.Type: array Maximum items: 3 |
| / |
an instant in UTC (ISO 8601) Type: string |
| / |
the running run's id Type: ["string","null"] |
| / |
|
| / |
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"] |
| / |
Type: null |
| / |
Type: array |
| / |
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"] |
| / |
Type: string |
| / |
$ref: #/shapes/page |
| / |
Present where the request carried wait_seconds. True where the answer's own reads found no run of the environment in flight, whatever ended the wait. False means a run was still in flight when the answer was read, not that it failed: its row's in_flight identifies it, detail says so, and another call with wait_seconds holds until it ends. The wait ends at its bound, when your connection or the platform's process ends it, or at once where this application's one held wait, an act's own among them, or the platform's fifty are already held.Type: boolean |
| / |
Present where the request carried wait_seconds: the milliseconds the answer was held before its reads.Type: integer Minimum: 0 |
Complete payload contract #
{
"request": {
"type": "object",
"required": [
"application"
],
"properties": {
"application": {
"type": "string",
"description": "Your account's application `id` from `list_applications`, not its name or label."
},
"environment": {
"type": "string",
"description": "The environment, `development` or `production`, production by default; any other name draws `invalid_request` at its path."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "The most recent runs returned per schedule, 1 to 100, 5 by default."
},
"wait_seconds": {
"type": "integer",
"minimum": 1,
"maximum": 45,
"description": "Optional: seconds to hold the answer until no run of the environment read is in flight; absent, it returns at once. Out of range is refused `invalid_request`."
}
}
},
"response": {
"type": "object",
"required": [
"contract_version",
"application",
"environment",
"halted",
"window_seconds",
"schedules"
],
"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."
},
"application": {
"type": "string"
},
"environment": {
"type": "string"
},
"halted": {
"type": [
"object",
"boolean"
],
"required": [
"at",
"by"
],
"properties": {
"at": {
"type": "string",
"description": "The instant the halt began, in UTC (ISO 8601)."
},
"by": {
"type": "string",
"enum": [
"developer",
"platform"
],
"description": "Who halted the environment: `developer` through `halt_environment`, or `platform` through the activity cap of the daily pass (PLD-L0-41)."
}
},
"description": "False where the environment is running, never true; otherwise the halt's instant and author, during which no row of the environment is claimed and each row's `next_due` stays where it was (PLD-L0-41; SCH-L0-03)."
},
"window_seconds": {
"type": "integer",
"description": "the schedule kind's bounded execution window, in seconds: a platform setting, the same for every application, so `read_plan_quotas` has no row for it, and the wake of a stopped environment by a due run counts against it (HST-L0-02)"
},
"read_at": {
"type": "string",
"description": "The instant of this read, ISO 8601 in UTC, shared by every row's `cron_preview`. Compare a row's `next_due` or `cron_preview` with `read_at` to see whether that time has passed or how long remains."
},
"schedules": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"cron",
"path",
"deployed",
"reason",
"next_due",
"in_flight",
"last_run",
"runs"
],
"properties": {
"name": {
"type": "string"
},
"cron": {
"type": "string"
},
"path": {
"type": "string"
},
"deployed": {
"type": "boolean",
"description": "whether the environment holds a deploy or promote made at or after the declaration"
},
"reason": {
"type": [
"string",
"null"
],
"enum": [
"no_deploy",
"awaiting_deploy",
null
],
"description": "set where deployed is false: the environment holds no version, or the declaration is newer than its last deploy"
},
"next_due": {
"type": [
"string",
"null"
]
},
"cron_preview": {
"type": "array",
"maxItems": 3,
"items": {
"type": "string",
"description": "an instant in UTC (ISO 8601)"
},
"description": "On every row: up to three instants the cron yields, in order, the first after `read_at`, each within 366 days of it. Where `deployed` is true and the answer's `halted` is false, the platform claims them in turn, and at each claim a run starts or its outcome is recorded. The outcome is skipped where another run is in flight, the account is suspended, or the router refuses the fire, and missed where the claim is late past the tolerance (SCH-L0-04). A claim late inside it advances past a due time it did not take, which is neither run nor recorded. Before the deploy a row waits for, and during a halt, no instant is claimed (SCH-L0-07)."
},
"in_flight": {
"type": [
"string",
"null"
],
"description": "the running run's id"
},
"last_run": {
"oneOf": [
{
"type": "object",
"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."
}
}
},
{
"type": "null"
}
]
},
"runs": {
"type": "array",
"items": {
"type": "object",
"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."
}
}
}
}
}
}
},
"detail": {
"type": "string"
},
"page": {
"$ref": "#/shapes/page"
},
"settled": {
"type": "boolean",
"description": "Present where the request carried `wait_seconds`. True where the answer's own reads found no run of the environment in flight, whatever ended the wait. False means a run was still in flight when the answer was read, not that it failed: its row's `in_flight` identifies it, `detail` says so, and another call with `wait_seconds` holds until it ends. The wait ends at its bound, when your connection or the platform's process ends it, or at once where this application's one held wait, an act's own among them, or the platform's fifty are already held (MAPI-04)."
},
"waited_ms": {
"type": "integer",
"minimum": 0,
"description": "Present where the request carried `wait_seconds`: the milliseconds the answer was held before its reads."
}
}
}
}
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