2026-09-26에이전트

Sume API로 스케줄 에이전트 실행 목록 조회: 스케줄 점검하기

GET /v1/actions(limit, status, trigger_type)로 Sume 스케줄을 나열하고 각 실행 기록은 커서로 넘기며, cron과 API 실행은 trigger.source로 구분하세요.

읽는 시간 5분Sume

Sume API로 스케줄 에이전트 실행 목록을 보려면 GET /v1/actions를 호출해 스케줄 현황을 파악하고(status나 trigger_type으로 필터링), 그다음 GET /v1/actions/{action_id}/runs로 스케줄마다 실행 기록을 페이지 단위로 읽으세요. has_more가 false가 될 때까지 next_cursor를 cursor로 다시 넘기면 됩니다.

세부 내용은 2026-09-26에 확인한 Sume 문서 Scheduled, 실행과 결과, API 레퍼런스 페이지와 OpenAPI 레퍼런스에서 가져왔습니다. Scheduled는 제품 이름이고, API 네임스페이스는 /v1/actions입니다. 스케줄을 만들고 트리거하는 방법은 AI 영상 에이전트 스케줄 실행에서 다룹니다.

내 스케줄 목록은 어떻게 보나요?

GET /v1/actions에는 actions:read가 있는 키가 필요합니다. limit(1–100, 기본값 50), status(active 또는 inactive), trigger_type(cron 또는 api)을 받으며, 실행 목록과 같은 커서 규칙으로 페이지를 넘깁니다. 스케줄 하나는 GET /v1/actions/{action_id}로 읽습니다.

curl -sS "https://api.sume.com/v1/actions?status=active&trigger_type=cron&limit=100" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  | jq '.data[] | {id, title, next: .cron.next_run_at, last_run_at, has_api: .api_trigger_enabled}'

점검할 때는 스케줄의 어떤 필드를 봐야 하나요?

공개 형태에는 instructions 텍스트가 의도적으로 빠져 있으니, 지시문은 대시보드에서 읽고 수정하세요. 점검에 필요한 나머지는 모두 객체에 있습니다.

Scheduled, 고급: API로 스케줄 실행하기, API 레퍼런스 기준, 2026-09-26 확인.
필드	알 수 있는 것
`status`	`active` 또는 `inactive`. 비활성 스케줄은 API 실행을 거부함
`trigger_type`	`cron` 또는 `api`. 생성 시점에 고정됨
`api_trigger_enabled`	`POST /v1/actions/{action_id}/runs` 허용 여부. cron 스케줄도 켤 수 있음
`cron`	`{ expr, timezone, next_run_at }`. API 전용 스케줄이면 `null`
`last_run_at`	날짜·시간 또는 `null`. 모든 스케줄에 있음
`generation_spend_cap_usd_micros`	실행당 생성 상한. `null`이면 기본값 $1.00이 적용됨
`invoke_url`, `vanity_invoke_url`	영구적인 불투명 경로, 그리고 `{handle}/{slug}` 경로 또는 `null`

스케줄의 실행 기록은 어떻게 페이지를 넘겨 읽나요?

GET /v1/actions/{action_id}/runs는 limit을 1부터 100까지 받고(기본값 50), { data, has_more, next_cursor }를 반환합니다. has_more가 false가 될 때까지 next_cursor를 cursor로 다시 넘기세요. 커서는 불투명한 값이며, Sume가 발급하지 않은 커서는 400 invalid_request입니다. 실행 하나는 스케줄 아래의 GET /v1/actions/{action_id}/runs/{run_id}나 GET /v1/action-runs/{run_id}에서 읽을 수 있습니다.

curl -sS "https://api.sume.com/v1/actions/$ACTION_ID/runs?limit=100" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  | jq '{has_more, next_cursor, runs: [.data[] | {id, status, source: .trigger.source, created_at}]}'

cron 실행과 API 실행은 어떻게 구분하나요?

cron이든 수동이든 API든, 발동할 때마다 영수증이 딸린 실행이 만들어집니다. 영수증에서 다음 필드를 읽으세요.

trigger.source: cron, manual, api 중 하나이며 idempotency_key 옆에 있습니다. 대시보드의 실행 기록에서는 API로 시작한 실행에 API, 주기에 따라 실행된 것에 Cron 라벨이 붙습니다.
status: queued, processing, completed, failed, canceled(l 하나), skipped 중 하나입니다. Job 쪽 상태 문자열이 그대로 통한다고 가정하지 마세요.
skip_reason: 건너뛴 실행에서는 previous_run_active입니다. 멱등성 재전송이면 idempotency_hit이 true입니다.
output_schema.source: default, action_default, request_override 중 하나입니다.
request_id: 지원 요청에 쓸 수 있도록 로그에 남기세요.

handle과 slug로 스케줄을 읽을 수 있나요?

네. GET /v1/actions/{handle}/{slug}와 GET /v1/actions/{handle}/{slug}/runs는 불투명 경로와 똑같이 동작합니다. 예를 들면 /v1/actions/acme/weekly-teaser/runs입니다. 그래도 저장할 때는 불투명 aut_… id를 쓰세요. handle이나 slug 이름을 바꾸면 버니티 경로가 달라지고, 이름을 바꾼 handle은 90일 동안 계속 해석되지만 문서는 이를 보장이 아니라 마이그레이션 기간이라고 설명합니다.

slug는 소문자 영숫자를 하이픈 하나로 구분한 형태이고, 2–64자이며, 계정 안에서 고유해야 하고, runs는 예약어입니다. slug가 생기기 전에 만든 스케줄은 slug가 null이고, 둘 중 하나를 모르면 vanity_invoke_url이 null입니다. 모르는 handle, 모르는 slug, 소유하지 않은 handle은 모두 같은 404 action_not_found를 반환합니다.

API로 모니터링할 수 없는 것은 무엇인가요?

AI 영상 에이전트 스케줄 실행에 정리된 Scheduled의 미지원 항목은 모니터링의 한계이기도 합니다. 실행 이벤트 엔드포인트, 생성·수정 엔드포인트, MCP·CLI 접근이 없고, 팀 워크스페이스가 소유한 스케줄에는 API로 접근할 수 없습니다. 점검에 중요한 한계가 세 가지 더 있습니다.

실행 목록은 스케줄별입니다. API 레퍼런스에는 여러 스케줄의 실행을 한꺼번에 나열하는 라우트가 없으므로, 먼저 GET /v1/actions의 결과를 순회하세요.
실행 목록은 limit과 cursor만 받습니다. status나 trigger.source로 거르는 일은 여러분의 코드에서 하세요.
영수증의 usage.billable_amount_usd_micros는 그 실행에 귀속된 생성 지출입니다. 에이전트 자체의 LLM 턴은 빠지므로 실행의 총비용이 아니며, 권위 있는 과금 기록은 여전히 GET /v1/usage입니다.

출처

작성자 Sume