룰렛 내역 | 잼쿠봇 개발자센터

룰렛을 돌린 기록을 최신순으로 페이지 단위로 조회합니다. 명령어·후원으로 돌린 룰렛과 대시보드에서 돌린 룰렛 테스트가 모두 기록됩니다.

룰렛 내역 조회

룰렛이 한 번 돌 때마다 한 행이 쌓이며, 연차로 돌리면 회차마다 한 행씩 쌓입니다. 시청자 닉네임·룰렛 이름·기간으로 거를 수 있습니다.

GET/api/v1/developer/roulette-log권한: roulettelog:read

요청

이름	위치	타입	필수	설명
`page`	query	integer	아니요	페이지 번호. 1부터 시작하며 기본값은 1입니다
`size`	query	integer	아니요	한 페이지의 행 수. 1~200, 기본값은 20입니다
`nickname`	query	string	아니요	이 닉네임인 시청자의 기록만 돌려줍니다. 정확히 일치해야 합니다
`roulette_name`	query	string	아니요	이 이름인 룰렛의 기록만 돌려줍니다. 정확히 일치해야 합니다
`start_date`	query	string	아니요	이 시각 이후(같은 시각 포함)의 기록만 돌려줍니다. 형식 `YYYY-MM-DD HH:MM:SS`
`end_date`	query	string	아니요	이 시각 이전(같은 시각 포함)의 기록만 돌려줍니다. 형식 `YYYY-MM-DD HH:MM:SS`

nickname은 기록할 때의 닉네임이 아니라 지금 잼쿠봇에 저장된 닉네임과 비교합니다. 같은 닉네임을 쓰는 시청자가 여럿이면 모두 나옵니다.
roulette_name은 기록할 때의 룰렛 이름과 비교합니다. 룰렛 이름을 바꿔도 이전 기록의 이름은 바뀌지 않습니다.
특정 날짜 전체를 조회하려면 시작을 00:00:00, 종료를 23:59:59로 넣습니다. 시각은 한국 시간입니다.
쿼리 값의 공백과 콜론은 URL 인코딩합니다. 서버가 날짜 형식을 검사하지 않으니 위 형식을 그대로 지켜 보내세요.

GET /api/v1/developer/roulette-log?page=1&size=20&start_date=2026-10-05%2000%3A00%3A00&end_date=2026-10-05%2023%3A59%3A59
Authorization: Bearer ACCESS_TOKEN

응답

필드	타입	설명
`page`	integer	요청한 페이지 번호
`size`	integer	요청한 페이지 크기
`total_page`	integer	전체 페이지 수. 조건에 맞는 기록이 없으면 0
`total`	integer	조건에 맞는 전체 기록 수
`has_next`	boolean	다음 페이지가 있으면 `true`
`has_prev`	boolean	`page`가 2 이상이면 `true`
`next`	boolean	`has_next`와 같은 값. 이전 버전 호환용입니다
`data`	array	기록 목록. 최신순(`used_time` 내림차순)이며 범위를 벗어난 페이지는 빈 배열
`data[].streamer_uid`	string	채널 UID
`data[].user_uid`	string	룰렛을 돌린 시청자 UID. 익명 후원은 `anonymous`, 대시보드의 테스트유저는 `TEST`
`data[].used_time`	string	돌린 시각. 타임존 표기가 없는 ISO 8601 형식이며 한국 시간입니다. 밀리초가 0이면 소수점 부분이 빠집니다
`data[].roulette_name`	string	기록할 때의 룰렛 이름
`data[].result`	string	당첨 항목
`data[].nickname`	string	시청자 닉네임. 지금 잼쿠봇에 저장된 값입니다

{
  "page": 1,
  "next": true,
  "total_page": 3,
  "total": 47,
  "size": 20,
  "has_next": true,
  "has_prev": false,
  "data": [
    {
      "streamer_uid": "0123456789abcdef0123456789abcdef",
      "user_uid": "fedcba9876543210fedcba9876543210",
      "used_time": "2026-10-05T21:14:03.512000",
      "roulette_name": "간식 룰렛",
      "result": "치킨",
      "nickname": "시청자닉네임"
    }
  ]
}

다음 페이지는 has_next로 판단합니다. size·has_next·has_prev는 포인트 목록과 같은 이름으로 2026-10-05 에 추가됐고, 예전 키 next도 그대로 남아 있습니다. 공통 규칙은 페이지네이션을 참고하세요.

오류

상태	응답	원인
422	`{"detail": [...]}`	`page`가 1보다 작거나, `size`가 1~200을 벗어났거나, 둘 중 하나가 정수가 아닙니다
401, 403	공통 오류	토큰이 유효하지 않거나 `roulettelog:read` 권한이 없습니다

이 가이드로 해결이 안 됐나요?

디스코드로 문의하기