페이지네이션

API 응답에 한 번에 반환할 수 있는 것보다 더 많은 결과가 포함된 경우, 페이지네이션을 사용해 모든 페이지의 데이터를 조회하세요.

페이지네이션 작동 방식

max_results로 초기 요청을 만드세요
meta 객체에서 next_token이 있는지 응답을 확인하세요
있는 경우 해당 토큰을 pagination_token으로 사용해 다른 요청을 만드세요
next_token이 반환되지 않을 때까지 반복하세요

# Initial request
curl "https://api.x.com/2/users/12345/tweets?max_results=100" \
  -H "Authorization: Bearer $TOKEN"

# Response includes next_token
# {"data": [...], "meta": {"next_token": "abc123", ...}}

# Next page
curl "https://api.x.com/2/users/12345/tweets?max_results=100&pagination_token=abc123" \
  -H "Authorization: Bearer $TOKEN"

페이지네이션 토큰

토큰	설명
`next_token`	응답 `meta`에 있음. 다음 페이지를 가져올 때 사용.
`previous_token`	응답 `meta`에 있음. 이전 페이지로 돌아갈 때 사용.
`pagination_token`	요청 파라미터. `next_token` 또는 `previous_token` 값으로 설정.

응답 구조

{
  "data": [
    {"id": "1234", "text": "..."},
    {"id": "1235", "text": "..."}
  ],
  "meta": {
    "result_count": 100,
    "next_token": "7140w9gefhslx3",
    "previous_token": "77qp89slxjd"
  }
}

더 이상 결과가 없으면 next_token이 생략됩니다:

{
  "data": [...],
  "meta": {
    "result_count": 42,
    "previous_token": "77qp89abc"
  }
}

페이지네이션 파라미터

파라미터	설명	기본값
`max_results`	페이지당 결과 수	Endpoint에 따라 다름
`pagination_token`	이전 응답의 토큰	없음

특정 max_results 한도는 각 endpoint의 API 레퍼런스를 확인하세요.

예시: 모든 결과 페이지네이션

Python
JavaScript

Example

import requests

def get_all_tweets(user_id, bearer_token):
    url = f"https://api.x.com/2/users/{user_id}/tweets"
    headers = {"Authorization": f"Bearer {bearer_token}"}
    params = {"max_results": 100}
    
    all_tweets = []
    
    while True:
        response = requests.get(url, headers=headers, params=params)
        data = response.json()
        
        if "data" in data:
            all_tweets.extend(data["data"])
        
        # Check for next page
        next_token = data.get("meta", {}).get("next_token")
        if not next_token:
            break
            
        params["pagination_token"] = next_token
    
    return all_tweets

Example

async function getAllTweets(userId, bearerToken) {
  const url = `https://api.x.com/2/users/${userId}/tweets`;
  const headers = { Authorization: `Bearer ${bearerToken}` };
  
  let allTweets = [];
  let paginationToken = null;
  
  do {
    const params = new URLSearchParams({ max_results: 100 });
    if (paginationToken) {
      params.set("pagination_token", paginationToken);
    }
    
    const response = await fetch(`${url}?${params}`, { headers });
    const data = await response.json();
    
    if (data.data) {
      allTweets.push(...data.data);
    }
    
    paginationToken = data.meta?.next_token;
  } while (paginationToken);
  
  return allTweets;
}

모범 사례

최대 결과 사용

API 호출을 최소화하려면 허용된 최대 max_results를 요청하세요.

부분 페이지 처리

마지막 페이지는 max_results보다 적은 결과를 가질 수 있습니다.

토큰 저장

나중에 페이지네이션을 재개해야 하는 경우 next_token을 저장하세요.

페이지네이션으로 폴링하지 않기

새 데이터의 경우 반복 페이지네이션 대신 since_id를 사용하세요.

결과 정렬

결과는 최신순(역시간순) 으로 반환됩니다:

첫 페이지의 첫 결과 = 가장 최근
마지막 페이지의 마지막 결과 = 가장 오래된 것

이는 페이지 내부와 페이지 간에 모두 적용됩니다.

참고 사항

페이지네이션 토큰은 불투명한 문자열입니다 — 파싱하거나 수정하지 마세요
토큰은 일정 시간 후 만료될 수 있습니다
max_results보다 적은 결과를 받으면 더 많은 결과가 존재할 수 있습니다(next_token이 없을 때까지 계속하세요)
자동 페이지네이션 처리를 위해 SDK를 사용하세요

Getting Started

Products

Fundamentals

Partners & Customers

Resources

페이지네이션

페이지네이션 작동 방식

페이지네이션 토큰

응답 구조

페이지네이션 파라미터

예시: 모든 결과 페이지네이션

모범 사례

최대 결과 사용

부분 페이지 처리

토큰 저장

페이지네이션으로 폴링하지 않기

결과 정렬

참고 사항

다음 단계

Rate limit

SDK

​페이지네이션 작동 방식

​페이지네이션 토큰

​응답 구조

​페이지네이션 파라미터

​예시: 모든 결과 페이지네이션

​모범 사례

최대 결과 사용

부분 페이지 처리

토큰 저장

페이지네이션으로 폴링하지 않기

​결과 정렬

​참고 사항

​다음 단계

Rate limit

SDK

페이지네이션 작동 방식

페이지네이션 토큰

응답 구조

페이지네이션 파라미터

예시: 모든 결과 페이지네이션

모범 사례

결과 정렬

참고 사항

다음 단계