run_schedule

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/run_schedule, with a bearer credential and the action's payload as the JSON body.

Contract description

Fire one declared schedule now as a manual run: answered `running` at once and read back through `read_schedules`. With `wait_seconds` (1 to 45), the answer is held until the run ends, the store read every two seconds, and it carries `settled` and `waited_ms`. While the run is still running, `next` names the `read_schedules` call that waits on it. It is refused `run_in_flight` while the schedule's last run is still running and `schedule_not_deployed` where the environment holds no deploy or promote made at or after the declaration. For production that act is the deploy on an application with one environment, and the promote on one with two. A retry carrying the same `request_id` answers the same run.

An 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 answers the run it started where it did.

Access and action metadata

{
  "name": "run_schedule",
  "resource": "application",
  "tier": "reversible",
  "clients": [
    "bearer",
    "browser_session"
  ],
  "summary": "Fire one declared schedule now as a manual run: answered `running` at once and read back through `read_schedules`; refused `run_in_flight` while the schedule's last run is still running and `schedule_not_deployed` where the environment holds no deploy or promote made at or after the declaration (for production, the deploy on one environment and the promote on two); a retry carrying the same `request_id` answers the same run. With `wait_seconds` (1 to 45), the answer is held until the run ends, and it carries `settled` and `waited_ms`, and `next` while the run is still running.\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 answers the run it started where it did.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "openWorldHint": true
  }
}

MCP catalog entry

{
  "name": "run_schedule",
  "tier": "reversible",
  "scenario": "CHI-L0-09",
  "summary": "Fire one declared schedule now as a manual run: answered `running` at once and read back through `read_schedules`. With `wait_seconds` (1 to 45), the answer is held until the run ends, the store read every two seconds, and it carries `settled` and `waited_ms`. While the run is still running, `next` names the `read_schedules` call that waits on it. It is refused `run_in_flight` while the schedule's last run is still running and `schedule_not_deployed` where the environment holds no deploy or promote made at or after the declaration. For production that act is the deploy on an application with one environment, and the promote on one with two. A retry carrying the same `request_id` answers the same run.\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 answers the run it started where it did.",
  "owners": [
    "SVC-L0-15",
    "MAPI-04"
  ]
}

request

JSON pointer	Description and constraints
"" (root)	Type: object Required fields: ["application","schedule","request_id"]
/properties/application	Application ID returned by list_applications. The application must belong to the acting account. Type: string
/properties/schedule	Nonempty name of a schedule declared for the selected environment. Its declaration must be included in an eligible deployment before a manual run can start. Type: string
/properties/environment	The environment name, development or production. Omission or an empty value selects production. Type: string
/properties/request_id	Nonempty identifier for this manual-run request, scoped to the application across schedules and environments. Reuse it only to retry the same request; use a new value for a new run. After checking the requested schedule and its deployment eligibility, a repeated value returns the earlier run, even if that run belongs to another schedule or environment. Type: string
/properties/wait_seconds	Optional. The seconds, 1 to 45, the answer is held until the run this call answers ends: the run it started, or the run a repeated `request_id` names. The platform reads the run every two seconds and stops once this many seconds have passed since the call arrived, then answers with `settled` and `waited_ms`. Absent, the call answers at once, a run it started `running`. The wait takes the application's one held place, so a concurrent held `read_status` or `read_schedules` answers at once, from its own read. 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)	Without `wait_seconds`, answered at once with the run as the start read it, `running` for a run this call started, its end read through `read_schedules` (SCH-L0-06). With `wait_seconds`, the answer is held until the run ends: settled, it carries the run's outcome; unsettled, it carries `next` (MAPI-04; SCH-L0-06). Every answer is 200. Type: object Required fields: ["contract_version","run"]
/properties/contract_version	Required value: 1
/properties/reference	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}$
/properties/run	The run this call started, or the run a repeated `request_id` names. 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 answer 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"]
/properties/run/properties/id	Type: string
/properties/run/properties/schedule	Type: string
/properties/run/properties/environment	Type: string
/properties/run/properties/trigger	Type: string Allowed values: ["schedule","manual"]
/properties/run/properties/due	the due instant in UTC (ISO 8601) Type: string
/properties/run/properties/started_at	Type: ["string","null"]
/properties/run/properties/ended_at	Type: ["string","null"]
/properties/run/properties/outcome	Type: string Allowed values: ["running","succeeded","failed","window_ended","unreachable","skipped","missed","abandoned"]
/properties/run/properties/status	the handler's HTTP status where it answered Type: ["integer","null"]
/properties/run/properties/duration_ms	Type: ["integer","null"]
/properties/run/properties/detail	Type: ["string","null"]
/properties/settled	Present where the request carried `wait_seconds`. True where the one read after the wait found the run this call answers 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` names the call that waits on it (MAPI-04; SCH-L0-06). Type: boolean
/properties/waited_ms	Present where the request carried `wait_seconds`: the milliseconds the answer was held before its read of the run. Type: integer Minimum: 0
/properties/next	Present where the wait did not settle: the exact call that reads the run to its end, `read_schedules` naming the run's environment, with `wait_seconds` 45. Type: object Required fields: ["action","arguments"] Additional properties: false
/properties/next/properties/action	Required value: read_schedules
/properties/next/properties/arguments	Type: object Required fields: ["application","environment","wait_seconds"] Additional properties: false
/properties/next/properties/arguments/properties/application	Type: string
/properties/next/properties/arguments/properties/environment	Type: string Allowed values: ["development","production"]
/properties/next/properties/arguments/properties/wait_seconds	Required value: 45
/properties/detail	Without `wait_seconds`, names 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, names how the run ended, 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": "Application ID returned by list_applications. The application must belong to the acting account."
      },
      "schedule": {
        "type": "string",
        "description": "Nonempty name of a schedule declared for the selected environment. Its declaration must be included in an eligible deployment before a manual run can start."
      },
      "environment": {
        "type": "string",
        "description": "The environment name, development or production. Omission or an empty value selects production."
      },
      "request_id": {
        "type": "string",
        "description": "Nonempty identifier for this manual-run request, scoped to the application across schedules and environments. Reuse it only to retry the same request; use a new value for a new run. After checking the requested schedule and its deployment eligibility, a repeated value returns the earlier run, even if that run belongs to another schedule or environment."
      },
      "wait_seconds": {
        "type": "integer",
        "minimum": 1,
        "maximum": 45,
        "description": "Optional. The seconds, 1 to 45, the answer is held until the run this call answers ends: the run it started, or the run a repeated `request_id` names. The platform reads the run every two seconds and stops once this many seconds have passed since the call arrived, then answers with `settled` and `waited_ms`. Absent, the call answers at once, a run it started `running`. The wait takes the application's one held place, so a concurrent held `read_status` or `read_schedules` answers at once, from its own read. A value outside that range is refused `invalid_request`, its detail naming 45 as the bound."
      }
    }
  },
  "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 this call under, ten lowercase hexadecimal characters, the value the call’s record row carries; quote it when reporting the call."
      },
      "run": {
        "type": "object",
        "description": "The run this call started, or the run a repeated `request_id` names. 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 answer 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"
        ],
        "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"
            ]
          }
        }
      },
      "settled": {
        "type": "boolean",
        "description": "Present where the request carried `wait_seconds`. True where the one read after the wait found the run this call answers 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` names 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 where the wait did not settle: the exact call that reads the run to its end, `read_schedules` naming the run's environment, with `wait_seconds` 45."
      },
      "detail": {
        "type": "string",
        "description": "Without `wait_seconds`, names 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, names how the run ended, or the `next` call where it is still running."
      }
    },
    "description": "Without `wait_seconds`, answered at once with the run as the start read it, `running` for a run this call started, its end read through `read_schedules` (SCH-L0-06). With `wait_seconds`, the answer is held until the run ends: settled, it carries the run's outcome; 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