保存済みのワークフローを、決めた時刻に開始します。すべてのキーで、スケジュールの一覧表示と取得、今すぐの開始ができます。作成、変更、削除にはオーナーまたは管理者が必要です。開始の仕組みについては、スケジュールをご覧ください。
スケジュールを作成
POST
/v1/schedulesワークフローが、今すぐ受け付けられる実行に解決されることを確認してから、スケジュールを保存します。スケジュールとともに
201 を返します。ボディ
workflowstring必須開始する保存済みワークフローの名前。
cronstring必須5 フィールドの cron 式、または
@daily や @every 90m などの省略記法。開始は最短で 1 分に 1 回です。timezonestringタイムテーブルを解釈する IANA タイムゾーン。
Europe/Madrid など。デフォルトは UTC。namestring人が見るためのラベル。最大 128 文字。
inputany JSONすべての実行に渡す入力。最大 1 MiB。
max_cost_microsintegerすべての実行の予算。省略するとデフォルトの予算になります。
skip_if_runningboolean前回の実行がまだ続いている間は、開始をスキップします。デフォルトは
true。enabledbooleanデフォルトは
true。curl -X POST $EPHEMERAL_URL/v1/schedules \
-H "Authorization: Bearer $EPHEMERAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow": "welcome-new-customers",
"name": "Weekday welcome emails",
"cron": "0 9 * * 1-5",
"timezone": "Asia/Tokyo",
"input": { "signed_up": "yesterday" },
"max_cost_micros": 200000
}'Ephemeral が設定するスケジュールのフィールド
next_run_atstring | null次の開始時刻 (UTC)。スケジュールがオフの間は
null。last_run_atstringスケジュールが最後に実行時刻を迎えた日時。
last_run_idstring最後に開始した実行。
last_errorstring直近の開始がスキップまたは失敗した理由、あるいはスケジュールが一時停止した理由。開始に成功した後は空になります。
failuresinteger連続して失敗した開始の回数。5 回に達すると、スケジュールは自動的にオフになります。
タイムテーブルをプレビュー
POST
/v1/schedules/previewcron と timezone を検証し、何も保存せずに、次の 5 回の開始時刻を返します。無効なタイムテーブルは、理由とともに 400 を返します。{ "next": ["2026-10-05T00:00:00Z", "2026-10-06T00:00:00Z", "2026-10-07T00:00:00Z", "2026-10-08T00:00:00Z", "2026-10-09T00:00:00Z"] }スケジュールを一覧
GET
/v1/schedules{"items": [...]} を古い順に返します。?workflow= を付けると、特定のワークフローのスケジュールだけを一覧できます。スケジュールを取得
GET
/v1/schedules/{id}スケジュールを更新
PATCH
/v1/schedules/{id}作成時のフィールドのうち、変更したいものを送信します。残りはそのままです。
cron または timezone を変更すると、次の開始は現在時刻から計算されます。一時停止中のスケジュールで enabled を true にすると、失敗の回数がクリアされます。今すぐ開始
POST
/v1/schedules/{id}/runタイムテーブルとは別に、スケジュールの入力と予算でワークフローを今すぐ開始します。スケジュールの ID を持つ実行とともに
202 を返します。スケジュールを削除
DELETE
/v1/schedules/{id}204 を返します。スケジュールが開始した実行の記録は残ります。スケジュールの実行
GET /v1/runs?schedule={id} は、スケジュールが開始した実行を新しい順に一覧します。ページ分割は、実行の一覧と同じです。
1 つの組織に作成できるスケジュールは最大 50 件です。