read_schedules
Generated automatically from the published contract sources.
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.
A script calls this action over HTTPS at POST https://turnzero.ai/api/v1/actions/read_schedules, with a bearer credential and the action's payload as the JSON body. It also accepts GET.
Contract description
Read an application's declared schedules for an environment. Each one carries its next due time in UTC, whether the environment is halted, whether the environment holds a deploy or promote made at or after the declaration, the run in flight, and the last run. For production that act is the deploy on an application with one environment, and the promote on one with two. It also carries the most recent runs with outcome, status, and duration. A declaration whose environment holds none answers `deployed: false` with the reason — no deploy, or a declaration awaiting one. With `wait_seconds` (1 to 45), the answer is held until no run of the environment is in flight, the store read every two seconds, and it carries `settled` and `waited_ms`.
Access and action metadata
{
"name": "read_schedules",
"resource": "application",
"tier": "observe",
"clients": [
"bearer",
"browser_session"
],
"summary": "An application's declared schedules for an environment — each one's next due time in UTC, 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), the run in flight, the last run, and the most recent runs with outcome, status, and duration; a declaration whose environment holds none answers `deployed: false` with the reason — no deploy, or a declaration awaiting one. 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",
"tier": "observe",
"scenario": "CHI-L0-09",
"summary": "Read an application's declared schedules for an environment. Each one carries its next due time in UTC, whether the environment is halted, whether the environment holds a deploy or promote made at or after the declaration, the run in flight, and the last run. For production that act is the deploy on an application with one environment, and the promote on one with two. It also carries the most recent runs with outcome, status, and duration. A declaration whose environment holds none answers `deployed: false` with the reason — no deploy, or a declaration awaiting one. With `wait_seconds` (1 to 45), the answer is held until no run of the environment is in flight, the store read every two seconds, and it carries `settled` and `waited_ms`.",
"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"] |
| / |
Type: string |
| / |
absent, production; a name that is neither development nor production refuses invalid_request at its path Type: string |
| / |
the most recent runs answered per schedule, 5 by default Type: integer Minimum: 1 Maximum: 100 |
| / |
Optional. The seconds, 1 to 45, the answer is held until no run of the environment read is in flight. The platform reads its store every two seconds and stops once this many seconds have passed since the call arrived, then answers with `settled` and `waited_ms`. Absent, the read answers at once. A value outside that range is refused `invalid_request`, its detail naming 45 as the bound. 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 this call under, ten lowercase hexadecimal characters, the value the call’s record row carries; quote it when reporting the call. Type: string Pattern: ^[0-9a-f]{10}$ |
| / |
Type: string |
| / |
Type: string |
| / |
Null where the environment is running; 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 stood (PLD-L0-41; SCH-L0-03). Type: ["object","null"] 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 (PLD-L0-41). Type: string Allowed values: ["developer","platform"] |
| / |
the schedule kind's bounded execution window, in seconds: a platform setting, the same on every plan, 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) Type: integer |
| / |
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 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 this answer's time, each within 366 days of it. It says what the cron yields, not that a run starts: a schedule fires from its deploy, so a row whose environment owes a deploy starts no run before it, and a halted environment starts none. 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"] |
| / |
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 answered Type: ["integer","null"] |
| / |
Type: ["integer","null"] |
| / |
Type: ["string","null"] |
| / |
Type: null |
| / |
Type: array |
| / |
Type: object Required fields: ["id","schedule","environment","trigger","due","started_at","ended_at","outcome","status","duration_ms","detail"] |
| / |
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 answered Type: ["integer","null"] |
| / |
Type: ["integer","null"] |
| / |
Type: ["string","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` names it, `detail` says so, and another call with `wait_seconds` holds until it ends. The wait ends at its bound, when the caller's 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). 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"
},
"environment": {
"type": "string",
"description": "absent, production; a name that is neither development nor production refuses invalid_request at its path"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "the most recent runs answered per schedule, 5 by default"
},
"wait_seconds": {
"type": "integer",
"minimum": 1,
"maximum": 45,
"description": "Optional. The seconds, 1 to 45, the answer is held until no run of the environment read is in flight. The platform reads its store every two seconds and stops once this many seconds have passed since the call arrived, then answers with `settled` and `waited_ms`. Absent, the read answers at once. A value outside that range is refused `invalid_request`, its detail naming 45 as the bound."
}
}
},
"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 this call under, ten lowercase hexadecimal characters, the value the call’s record row carries; quote it when reporting the call."
},
"application": {
"type": "string"
},
"environment": {
"type": "string"
},
"halted": {
"type": [
"object",
"null"
],
"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": "Null where the environment is running; 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 stood (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 on every plan, 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)"
},
"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 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 this answer's time, each within 366 days of it. It says what the cron yields, not that a run starts: a schedule fires from its deploy, so a row whose environment owes a deploy starts no run before it, and a halted environment starts none."
},
"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"
],
"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 answered"
},
"duration_ms": {
"type": [
"integer",
"null"
]
},
"detail": {
"type": [
"string",
"null"
]
}
}
},
{
"type": "null"
}
]
},
"runs": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"schedule",
"environment",
"trigger",
"due",
"started_at",
"ended_at",
"outcome",
"status",
"duration_ms",
"detail"
],
"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 answered"
},
"duration_ms": {
"type": [
"integer",
"null"
]
},
"detail": {
"type": [
"string",
"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` names it, `detail` says so, and another call with `wait_seconds` holds until it ends. The wait ends at its bound, when the caller's 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