페이지네이션(Pagination)이란? AI API 결과를 나눠 받는 방법

TL;DR

페이지네이션(Pagination)은 API가 큰 목록을 한 번에 모두 보내지 않고 작은 묶음으로 나눠 전달하는 방식입니다. 응답에 다음 페이지가 있다는 표시와 커서, 연속 토큰, 다음 링크가 들어 있으면 이를 다음 요청에 사용합니다. AI 배치 작업, 파일, 평가 결과, 사용량 기록을 자동으로 모을 때 첫 페이지만 저장하면 일부 데이터가 눈에 띄지 않게 빠지기도 합니다.

핵심 3줄 요약

• 핵심 1
  페이지네이션은 긴 목록을 여러 페이지로 나눠 응답 크기와 처리 부담을 관리합니다.
• 핵심 2
  다음 페이지는 응답이 돌려준 커서, 연속 토큰, 다음 링크로 이어 받습니다. 토큰을 임의로 만들거나 고치지 않습니다.
• 핵심 3
  성공 응답을 한 번 받았다고 전체 목록을 받은 것은 아닙니다. 더 보기 표시가 끝날 때까지 반복해야 합니다.

이 글에서 다룰 내용

페이지네이션을 한 문장으로 정의하면 무엇인가요?

한 문장 정의: 페이지네이션은 API의 큰 결과 목록을 일정한 크기의 페이지로 나누고, 다음 위치를 가리키는 값으로 나머지 결과를 이어 받게 하는 방식입니다.

Google의 API 설계 지침 AIP-158은 계속 커지는 목록을 페이지로 나눠야 한다고 설명합니다. 요청에는 한 페이지의 최대 항목 수와 페이지 토큰을, 응답에는 다음 페이지 토큰을 두는 구조가 대표적입니다.

서비스마다 필드 이름은 다릅니다. page_token과 next_page_token을 쓰기도 하고, after와 last_id, continuationToken, nextLink, has_more를 쓰기도 합니다. 이름은 달라도 현재 위치 다음부터 목록을 이어 받는 목적은 같습니다.

페이지네이션은 데이터를 삭제하거나 요약하는 기능이 아닙니다. 한 번의 응답에 담는 양만 나눕니다. 모든 페이지를 끝까지 모으면 API가 허용하는 범위의 전체 목록을 얻습니다.

한 줄 정리: 페이지네이션은 긴 목록을 버리는 방식이 아니라 여러 번에 걸쳐 안전하게 전달하는 방식입니다.

왜 AI API를 사용할 때 중요한가요?

AI 자동화는 답변 생성만 호출하지 않습니다. 업로드한 파일, 배치 작업, 평가 실행, 모델 목록, 조직 사용자, 사용량 기록처럼 여러 항목을 조회하는 API도 자주 씁니다. 항목이 늘면 서버가 한 번에 모두 보내기 어렵고 응답도 무거워집니다.

페이지네이션은 한 요청의 응답 크기와 처리 시간을 관리하는 데 도움이 됩니다. 클라이언트도 필요한 만큼만 받아 화면에 보여 주거나 작은 단위로 저장하고 처리합니다.

더 중요한 이유는 누락 방지입니다. 자동화가 첫 응답의 data만 저장하고 has_more, next_page_token, nextLink를 확인하지 않으면 첫 페이지 뒤의 항목은 수집되지 않습니다. 요청 자체는 성공하므로 오류가 겉으로 드러나지 않기 쉽습니다.

OpenAI의 배치 목록 API는 limit으로 한 번에 받을 수를 정하고 after 커서로 다음 목록을 요청하는 예를 제공합니다. 응답에는 first_id, last_id, has_more 같은 값이 포함됩니다. 실제 필드와 제한 범위는 사용하는 엔드포인트의 최신 문서를 확인해야 합니다.

감자나라ai님이 챗GPT 웹 화면에서 일반 대화를 할 때 페이지네이션을 직접 설정할 일은 거의 없습니다. AI API와 노코드 자동화 도구로 파일, 작업 내역, 로그를 모을 때는 결과가 한 번에 전부 오는지 반드시 확인해야 합니다.

핵심 인사이트: 페이지네이션을 모르면 API 호출은 성공했는데 보고서와 데이터베이스에는 일부 기록만 남는 문제가 생깁니다.

쉬운 예시로 이해해 볼까요?

AI 배치 작업이 230개 있고 API가 한 번에 최대 100개씩 돌려준다고 가정해 보겠습니다.

• 첫 요청: 작업 1번부터 100번까지 받습니다.
• 두 번째 요청: 첫 응답이 준 다음 위치로 이어서 101번부터 200번까지 받습니다.
• 세 번째 요청: 201번부터 230번까지 받습니다.
• 종료: 다음 페이지가 없다는 표시를 확인하고 반복을 멈춥니다.

첫 요청이 HTTP 200으로 성공했더라도 100개만 저장하고 끝내면 130개가 빠집니다. 반대로 마지막 페이지 뒤에도 계속 요청하면 같은 결과가 반복되거나 오류가 납니다. 다음 페이지 표식이 있을 때만 이어 가고, 끝났다는 조건을 명확히 두어야 합니다.

도서관에 책이 230권 있는데 한 상자에 100권씩 담아 옮기는 상황과 비슷합니다. 첫 상자를 잘 받았다는 사실은 모든 책을 받았다는 뜻이 아닙니다. 상자에 적힌 다음 순서를 보고 마지막 상자까지 확인해야 합니다.

예시 정리: 230개를 100개씩 받는다면 요청은 세 번 필요합니다. 첫 요청의 성공 여부와 전체 수집 완료 여부는 다른 문제입니다.

페이지네이션은 어떤 순서로 처리하나요?

1. 목록 API의 필드를 확인합니다

공식 문서에서 한 페이지 크기, 다음 위치 필드, 종료 조건을 찾습니다. 서비스에 따라 limit, page_size, after, page_token, has_more, nextLink처럼 다른 이름을 씁니다.

2. 첫 페이지를 요청합니다

필터, 정렬 순서, 페이지 크기를 정해 첫 요청을 보냅니다. 필요한 항목 수가 적다면 무조건 최대 크기로 요청할 필요는 없습니다.

3. 받은 항목을 저장하거나 처리합니다

현재 페이지의 항목을 데이터베이스나 파일에 넣습니다. 작업이 중단된 뒤 다시 시작하려면 마지막으로 처리한 커서와 항목 ID를 함께 기록합니다.

4. 다음 위치 값을 읽습니다

응답의 커서, 연속 토큰, 다음 링크를 확인합니다. Google AIP-158은 페이지 토큰을 내부 구조를 해석할 수 없는 불투명한 값으로 다루도록 권고합니다.

5. 같은 조건으로 다음 페이지를 요청합니다

다음 요청에서도 필터와 정렬 조건을 유지합니다. Google과 Microsoft 문서는 연속 토큰을 쓸 때 원래 요청의 다른 조건을 일관되게 유지해야 예상치 못한 결과를 줄인다고 설명합니다.

6. 종료 조건에서 멈춥니다

다음 토큰이나 링크가 비어 있거나 has_more가 거짓이면 반복을 끝냅니다. SDK가 자동 페이지네이션을 지원한다면 실제로 필요한 항목까지만 지연해서 가져오는지 확인합니다.

실전 팁: 수집한 항목 ID를 기준으로 중복을 막고, 마지막 성공 커서를 저장하면 네트워크 오류 뒤에도 처음부터 다시 받지 않아도 됩니다.

비슷한 용어와 무엇이 다른가요?

페이지네이션과 페이지 크기

페이지네이션은 목록을 나누는 전체 방식입니다. 페이지 크기는 한 번에 최대 몇 개를 받을지 정하는 값입니다. limit=100이라고 요청해도 서버가 항상 100개를 채워 준다고 가정하면 안 됩니다.

페이지네이션과 커서

커서는 목록에서 다음에 이어 받을 위치를 나타내는 표식입니다. 커서 기반 페이지네이션은 마지막 항목 ID나 서비스가 만든 토큰을 다음 요청에 넘기는 방식입니다. 페이지네이션이 큰 개념이고 커서는 이를 구현하는 방법 중 하나입니다.

커서와 연속 토큰

두 용어는 실무에서 비슷하게 쓰입니다. 커서는 위치라는 개념을 강조하고, 연속 토큰은 API가 돌려준 불투명한 값을 그대로 다시 보낸다는 점을 강조합니다. 서비스 문서의 필드 이름과 규칙을 따르는 것이 중요합니다.

커서 방식과 오프셋 방식

오프셋 방식은 offset=100처럼 앞에서 몇 개를 건너뛸지 숫자로 지정합니다. 이해하기 쉽지만 목록에 항목이 추가되거나 삭제되면 이동 중 중복이나 누락이 생기기 쉽습니다. 커서 방식은 정해진 위치 뒤에서 이어 받아 변하는 목록에 더 안정적인 경우가 많습니다.

페이지네이션과 스트리밍

스트리밍은 하나의 응답을 생성되는 순서대로 조금씩 보내는 방식입니다. 페이지네이션은 여러 목록 요청을 이어서 보내는 방식입니다. AI 답변의 토큰이 화면에 차례로 나타나는 것은 스트리밍이며, 파일 목록을 100개씩 여러 번 받는 것은 페이지네이션입니다.

페이지네이션과 배치 처리

배치 처리는 여러 작업을 모아 한 묶음으로 실행하는 방식입니다. 페이지네이션은 조회 결과를 여러 묶음으로 전달하는 방식입니다. 배치 작업 목록 자체가 길면 그 목록도 페이지네이션으로 조회합니다.

비교 정리: 스트리밍은 한 응답을 조금씩 보내고, 배치 처리는 작업을 묶어 실행하며, 페이지네이션은 긴 목록을 여러 요청으로 나눠 받습니다.

AI 개발과 자동화에서는 어떻게 쓰이나요?

첫째, 배치 작업 상태를 모을 때 씁니다. 완료, 실패, 진행 중인 작업의 전체 현황을 집계하려면 모든 페이지를 확인해야 합니다.

둘째, 업로드한 파일과 벡터 저장소 항목을 정리할 때 씁니다. 첫 페이지만 보고 오래된 파일이 없다고 판단하면 정리 대상이 남기도 합니다.

셋째, 평가와 실행 기록을 보고서로 만들 때 씁니다. 날짜 필터와 정렬 조건을 유지하며 페이지를 이어 받아야 기간별 수치가 맞습니다.

넷째, 관리 화면의 더 보기와 무한 스크롤에 씁니다. 사용자가 아래로 이동할 때 다음 페이지만 불러오면 처음부터 전체 목록을 내려받지 않아도 됩니다.

다섯째, 노코드 자동화에서 반복 단계로 구현합니다. 응답의 다음 토큰을 변수에 저장하고, 토큰이 없을 때까지 API 호출과 저장 단계를 반복합니다.

사용할 때 무엇을 주의해야 하나요?

첫째, 첫 페이지만 받고 끝내지 않습니다. HTTP 200은 해당 요청이 성공했다는 뜻이지 전체 목록 수집이 끝났다는 뜻은 아닙니다.

둘째, 커서나 토큰을 직접 해석하거나 고치지 않습니다. Google AIP-158과 Microsoft 문서는 페이지 토큰을 불투명한 값으로 다루도록 안내합니다. 응답에서 받은 값을 그대로 사용합니다.

셋째, 필터와 정렬 조건을 중간에 바꾸지 않습니다. 같은 연속 토큰을 쓰면서 조건을 바꾸면 오류가 나거나 예상하지 못한 목록이 돌아오기도 합니다.

넷째, 목록은 수집 중에도 바뀝니다. 새 항목 추가나 삭제 때문에 중복이나 누락 위험이 생깁니다. 안정된 정렬 키를 쓰고 항목 ID로 중복을 제거하며 중요한 작업은 수집 시점 범위를 고정합니다.

다섯째, 페이지 수만큼 API 호출이 늘어난다는 점을 계산합니다. 레이트 리밋, 비용, 타임아웃, 재시도 정책을 함께 설계합니다. 필요하지 않은 전체 목록을 매번 불러오지 않습니다.

여섯째, 페이지 토큰을 인증 수단으로 보지 않습니다. 토큰은 다음 위치를 알려 줄 뿐입니다. 각 요청에는 필요한 인증과 권한 검사가 별도로 적용됩니다.

주의: 페이지네이션 오류는 실패 메시지보다 불완전한 성공으로 나타나기 쉽습니다. 전체 항목 수, 마지막 페이지 도달 여부, 중복 ID를 함께 점검하세요.

자주 묻는 질문

Q1. API가 성공했다고 응답하면 전체 목록을 받은 것 아닌가요?

아닙니다. 성공 상태는 현재 페이지 요청이 처리됐다는 뜻입니다. has_more, 다음 토큰, 다음 링크가 남아 있다면 추가 요청이 필요합니다.

Q2. 커서와 페이지 번호 중 어느 방식이 더 좋은가요?

목록이 자주 바뀌면 커서 방식이 중복과 누락을 줄이는 데 유리한 경우가 많습니다. 특정 페이지로 바로 이동해야 하는 화면에는 페이지 번호나 오프셋이 편합니다. API가 제공하는 방식을 우선 따릅니다.

Q3. 연속 토큰은 나중에 다시 써도 되나요?

서비스마다 다릅니다. 토큰은 만료되거나 요청 조건에 묶일 수 있습니다. 장기 보관을 전제로 하지 말고 해당 API 문서의 유효 기간과 재개 규칙을 확인합니다.

Q4. 페이지네이션을 쓰면 레이트 리밋을 피할 수 있나요?

아닙니다. 페이지를 나누면 호출 횟수가 늘어납니다. 한 페이지 크기, 필요한 데이터 범위, 호출 간격, 재시도를 함께 조정해야 합니다.

Q5. 일반 챗GPT 사용자도 페이지네이션을 알아야 하나요?

일반 대화에서는 몰라도 됩니다. 챗GPT나 다른 AI의 API를 연결해 파일, 배치 작업, 로그, 사용량을 자동 수집한다면 반드시 알아둘 개념입니다.

출처

마무리

페이지네이션은 AI API의 긴 목록을 작은 페이지로 나누고 다음 위치 값으로 이어 받는 방식입니다. 자동화에서는 첫 페이지의 성공보다 마지막 페이지까지 도달했는지가 더 중요합니다.

초보자는 세 가지만 기억하면 됩니다. 응답에서 다음 페이지 표시를 찾고, 받은 커서나 토큰을 그대로 사용하며, 다음 표시가 사라질 때 반복을 멈춥니다.

감자나라ai님이 AI API로 목록을 모으는 자동화를 만든다면 첫 테스트에서 항목 수를 일부러 한 페이지보다 크게 만들어 보세요. 그래야 첫 페이지만 저장하는 숨은 누락을 발행이나 운영 전에 찾습니다.