> ## Documentation Index
> Fetch the complete documentation index at: https://generaltranslation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 페이지네이션

X API는 여러 페이지의 결과를 반환하는 엔드포인트(예: 타임라인, 검색 등)에 페이지네이션을 사용합니다. 각 API 응답에는 `result_count`, `previous_token`, `next_token`이 포함된 `meta` 객체가 있습니다. XDK는 `next_token`을 사용해 필요한 만큼의 API 호출을 자동으로 처리하므로, 개발자는 여러 번 호출을 직접 만들 필요 없이 원하는 데이터 양만 지정하면 됩니다.
SDK는 다음과 같이 이 작업을 단순화합니다:

* **내장 이터레이터**: 제너레이터 함수를 사용해 여러 페이지를 자연스럽게 연속해서 가져옵니다.
* **명시적 토큰 처리**: 필요할 때 `pagination_token`을 전달하여 유연하게 수동 제어할 수 있습니다.
* **최대 결과 수 준수**: 호출당 `max_results`를 준수합니다(검색의 경우 최대 100 등, API 한도 내).

<div id="automatic-pagination-recommended">
  ## 자동 페이지네이션(권장)
</div>

페이지네이션이 적용된 응답에서 `iterate()` 메서드를 사용해 모든 결과를 지연 로딩 방식으로 가져옵니다.
**예시: 페이지네이션 검색**

```python theme={null}
from xdk import Client
client = Client(bearer_token="your_bearer_token")
# 자동 페이지네이션으로 검색
all_posts = []
for page in client.posts.search_recent(
    query="python",
    max_results=100,  # 페이지당
    tweet_fields=["created_at", "author_id"]  # 선택적 확장
):
    all_posts.extend(page.data)
    print(f"Fetched {len(page.data)} Posts (total: {len(all_posts)})")
print(f"Total tweets: {len(all_posts)}")
```

* 이터레이터가 `next_token`을 자동으로 처리합니다.
* `next_token`이 더 이상 없으면 중지됩니다.
* 429 errors를 피하기 위한 rate limit 백오프를 지원합니다.

<div id="manual-pagination">
  ## 수동 페이지네이션
</div>

사용자 정의 로직(예: 페이지별 처리)에 따라 결과를 세밀하게 제어해야 하는 경우, 아래와 같이 `next_token`을 사용해 페이지네이션을 수동으로 처리할 수 있습니다.

```python theme={null}
# Get first page - search_recent returns an Iterator
first_page = next(client.posts.search_recent(
    query="xdk python sdk",
    max_results=100,
    pagination_token=None  # First page
))
print(f"First page: {len(first_page.data) if first_page.data else 0} Posts")
# Extract next_token from meta
next_token = None
if hasattr(first_page, 'meta') and first_page.meta:
    if hasattr(first_page.meta, 'next_token'):
        next_token = first_page.meta.next_token
    elif isinstance(first_page.meta, dict):
        next_token = first_page.meta.get('next_token')
if next_token:
    second_page = next(client.posts.search_recent(
        query="xdk python sdk",
        max_results=100,
        pagination_token=next_token
    ))
    print(f"Second page: {len(second_page.data) if second_page.data else 0} Posts")
```

**팁**:

* 엔드포인트마다 기본값이 다르므로, 항상 `max_results`를 지정해 최적화하세요.
* 디버깅을 위해 `meta.result_count`를 모니터링하세요.
* 매우 큰 쿼리의 경우, 블로킹을 피하기 위해 비동기 반복을 사용하는 것을 고려하세요.
  Python XDK를 사용한 자세한 코드 예시는 [code samples GitHub repo](https://github.com/xdevplatform/samples/tree/main/python)를 참고하세요.