read_schedules #

View this page as Markdown

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"]
/properties/application Your account's application id from list_applications, not its name or label.

Type: string
/properties/environment The environment, development or production, production by default; any other name draws invalid_request at its path.

Type: string
/properties/limit The most recent runs returned per schedule, 1 to 100, 5 by default.

Type: integer
Minimum: 1
Maximum: 100
/properties/wait_seconds 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"]
/properties/contract_version Required value: 1
/properties/reference 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}$
/properties/application Type: string
/properties/environment Type: string
/properties/halted 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"]
/properties/halted/properties/at The instant the halt began, in UTC (ISO 8601).

Type: string
/properties/halted/properties/by Who halted the environment: developer through halt_environment, or platform through the activity cap of the daily pass.

Type: string
Allowed values: ["developer","platform"]
/properties/window_seconds 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

Type: integer
/properties/read_at 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
/properties/schedules Type: array
/properties/schedules/items Type: object
Required fields: ["name","cron","path","deployed","reason","next_due","in_flight","last_run","runs"]
/properties/schedules/items/properties/name Type: string
/properties/schedules/items/properties/cron Type: string
/properties/schedules/items/properties/path Type: string
/properties/schedules/items/properties/deployed whether the environment holds a deploy or promote made at or after the declaration

Type: boolean
/properties/schedules/items/properties/reason 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]
/properties/schedules/items/properties/next_due Type: ["string","null"]
/properties/schedules/items/properties/cron_preview 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
/properties/schedules/items/properties/cron_preview/items an instant in UTC (ISO 8601)

Type: string
/properties/schedules/items/properties/in_flight the running run's id

Type: ["string","null"]
/properties/schedules/items/properties/last_run
/properties/schedules/items/properties/last_run/oneOf/0 Type: object
Required fields: ["id","schedule","environment","trigger","due","started_at","ended_at","outcome","status","duration_ms","detail","woke"]
/properties/schedules/items/properties/last_run/oneOf/0/properties/id Type: string
/properties/schedules/items/properties/last_run/oneOf/0/properties/schedule Type: string
/properties/schedules/items/properties/last_run/oneOf/0/properties/environment Type: string
/properties/schedules/items/properties/last_run/oneOf/0/properties/trigger Type: string
Allowed values: ["schedule","manual"]
/properties/schedules/items/properties/last_run/oneOf/0/properties/due the due instant in UTC (ISO 8601)

Type: string
/properties/schedules/items/properties/last_run/oneOf/0/properties/started_at Type: ["string","null"]
/properties/schedules/items/properties/last_run/oneOf/0/properties/ended_at Type: ["string","null"]
/properties/schedules/items/properties/last_run/oneOf/0/properties/outcome Type: string
Allowed values: ["running","succeeded","failed","window_ended","unreachable","skipped","missed","abandoned"]
/properties/schedules/items/properties/last_run/oneOf/0/properties/status the handler's HTTP status where it responded

Type: ["integer","null"]
/properties/schedules/items/properties/last_run/oneOf/0/properties/duration_ms Type: ["integer","null"]
/properties/schedules/items/properties/last_run/oneOf/0/properties/detail Type: ["string","null"]
/properties/schedules/items/properties/last_run/oneOf/0/properties/woke 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"]
/properties/schedules/items/properties/last_run/oneOf/1 Type: null
/properties/schedules/items/properties/runs Type: array
/properties/schedules/items/properties/runs/items Type: object
Required fields: ["id","schedule","environment","trigger","due","started_at","ended_at","outcome","status","duration_ms","detail","woke"]
/properties/schedules/items/properties/runs/items/properties/id Type: string
/properties/schedules/items/properties/runs/items/properties/schedule Type: string
/properties/schedules/items/properties/runs/items/properties/environment Type: string
/properties/schedules/items/properties/runs/items/properties/trigger Type: string
Allowed values: ["schedule","manual"]
/properties/schedules/items/properties/runs/items/properties/due the due instant in UTC (ISO 8601)

Type: string
/properties/schedules/items/properties/runs/items/properties/started_at Type: ["string","null"]
/properties/schedules/items/properties/runs/items/properties/ended_at Type: ["string","null"]
/properties/schedules/items/properties/runs/items/properties/outcome Type: string
Allowed values: ["running","succeeded","failed","window_ended","unreachable","skipped","missed","abandoned"]
/properties/schedules/items/properties/runs/items/properties/status the handler's HTTP status where it responded

Type: ["integer","null"]
/properties/schedules/items/properties/runs/items/properties/duration_ms Type: ["integer","null"]
/properties/schedules/items/properties/runs/items/properties/detail Type: ["string","null"]
/properties/schedules/items/properties/runs/items/properties/woke 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"]
/properties/detail Type: string
/properties/page $ref: #/shapes/page
/properties/settled 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
/properties/waited_ms 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 #