Sume API 페이지네이션: cursor·starting_after·한도

Sume API 목록은 세 가지 방식으로 페이지를 넘깁니다. Format, Action, 각각의 실행 목록, Agent Completion 실행 목록은 next_cursor와 has_more를 반환하며, 커서는 cursor로 다시 보냅니다. GET /v1/jobs는 data.next_cursor를 반환하고, 이 값은 starting_after로 다시 보냅니다. 아바타, 이벤트, 사용량, 검색 목록은 limit은 받지만 커서는 없고, 한 페이지만 반환합니다.

아래 한도는 라이브 OpenAPI 레퍼런스와 실행과 결과 (영문), Scheduled 실행 같은 표면별 문서 페이지에서 가져왔으며, 2026-09-27에 확인했습니다. 비정상 종료 뒤 복구를 포함해 Job 목록을 페이지별로 읽는 방법은 Job 목록 API에서 따로 설명합니다.

목록 엔드포인트마다 페이지를 어떻게 넘기나요?

각 행에는 해당 목록을 다루는 글을 링크했습니다. limit은 요청하는 페이지 크기입니다.

cursor와 has_more로 어떻게 페이지를 넘기나요?

첫 요청은 cursor 없이 보내세요. has_more가 true인 동안에는 next_cursor를 cursor로 다시 보내고, 마지막 페이지에서는 next_cursor가 null입니다. 같은 루프가 Format, Action, 세 가지 실행 목록 모두에 통합니다.

• 커서는 불투명한 값으로 다루세요. 받은 그대로 다시 넘기고, 파싱하거나 직접 만들지 마세요. Format과 Action 실행 목록에서는 Sume가 발급하지 않은 커서가 400 invalid_request로 거부됩니다.
• Format 실행 페이지는 (created_at, id) 기준 keyset이고 최신순이므로, 페이지를 넘기는 동안 새 실행이 생겨도 행이 밀리지 않습니다.
• API로 한 번도 실행하지 않은 Format은 404가 아니라 빈 목록을 반환합니다.

URL="https://api.sume.com/v1/formats/acme/product-promo/runs?limit=100"
NEXT=""
while :; do
  PAGE=$(curl -sS "$URL$NEXT" -H "Authorization: Bearer $SUME_API_KEY")
  echo "$PAGE" | jq -r '.data[] | [.id, .status] | @tsv'
  [ "$(echo "$PAGE" | jq -r '.has_more')" = "true" ] || break
  NEXT="&cursor=$(echo "$PAGE" | jq -r '.next_cursor | @uri')"
done

GET /v1/jobs는 왜 starting_after를 쓰나요?

Job 목록은 페이지를 넘기는 방식이 다릅니다. 행은 data.jobs에 최신순으로 담기고, data.next_cursor는 남은 Job이 더 있을 때만 있으며, 이 값은 starting_after로 다시 보냅니다. has_more는 없고, cursor는 Job 목록의 파라미터가 아니어서 보내면 400 unknown_parameter가 됩니다. Job 목록 API에서 이 루프와 잃어버린 Job ID를 복구하는 방법을 차례로 설명합니다.

한 페이지만 반환하는 목록은 무엇인가요?

다음 목록은 limit을 받고 일부는 필터도 받지만, 응답에 커서가 없습니다.

• GET /v1/avatars, GET /v1/avatar-1.0/avatars, GET /v1/avatar-videos는 status로 필터링하며, 여기서 ready는 완료된 Job의 별칭입니다.
• GET /v1/jobs/{id}/events는 Job 하나의 타임라인을 반환합니다.
• GET /v1/usage는 최신 원장 행을 나열합니다. run_id, thread_id, job_id를 붙이면 summary가 그 범위의 모든 행을 합산하고, limit은 나열되는 행 수만 제한합니다.
• GET /v1/formats/{handle}/{slug}/contents?recursive=1은 Format 패키지의 모든 파일을 본문과 함께 한 번의 호출로 반환합니다.

없는 목록은 무엇인가요?

다음 목록은 찾는 사람이 많지만 존재하지 않습니다.

• GET /v1/format-runs: 여러 Format에 걸친 실행 목록은 없습니다. Format별로 나열하거나, 생성할 때 저장한 실행 ID를 키로 삼아 자체 색인을 유지하세요.
• 대량 실행 큐 목록: 큐를 나열하는 공개 엔드포인트가 없으므로, 생성 응답에서 받은 큐 ID를 하나하나 저장하세요.
• 개인 Format과 팀 Format을 함께 보여 주는 목록: 보이는 범위는 키를 따릅니다. 개인 키는 개인 Format을, 팀 키는 그 워크스페이스의 Format을 나열하며, 어느 쪽도 다른 쪽의 Format은 나열하지 않습니다.

페이지를 넘길 때도 요청 한도가 차감되나요?

네. GET으로 읽는 모든 페이지는 읽기 요청입니다. API 키를 쓰면 읽기는 요금제 쓰기 숫자의 마흔 배를 별도 버킷으로 받으므로, 페이지 넘김 루프가 생성 요청에 쓸 예산을 잡아먹을 수 없습니다. 두 가지 POST 검색은 읽기가 아니라 쓰기 예산을 씁니다. 요금제별 예산은 Sume API 오류와 요청 한도에 나와 있습니다.