스케줄 · Ephemeral 문서

저장된 워크플로를 시간표에 따라 시작합니다. 모든 키로 스케줄을 조회하고 지금 시작할 수 있으며, 생성, 변경, 삭제에는 소유자나 관리자가 필요합니다. 시작 방식은 스케줄을 참고하세요.

스케줄 생성

POST/v1/schedules

워크플로가 지금 승인될 수 있는 실행으로 해석되는지 확인한 다음 스케줄을 저장합니다. 스케줄과 함께 201로 응답합니다.

본문

workflowstring필수

시작할 저장된 워크플로의 이름.

cronstring필수

다섯 필드의 cron 표현식, 또는 @daily, @every 90m 같은 약식 표기. 최대 분당 한 번.

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/preview

cron과 timezone을 검사하고, 아무것도 저장하지 않은 채 다음 다섯 번의 시작 시각을 반환합니다. 올바르지 않은 시간표는 사유와 함께 400을 반환합니다.

JSON

{ "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}는 스케줄이 시작한 실행을 최신순으로 나열하며, 페이징은 실행 목록과 같습니다.

조직당 스케줄은 최대 50개까지 만들 수 있습니다.