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

# 페이지네이션

> XDK 이터레이터를 사용하여 Python에서 X API 결과를 자동 next_token 처리로 페이징하거나, 사용자 지정 페이징 로직을 위해 pagination_token을 수동으로 관리하세요.

X API는 여러 페이지의 결과를 반환하는 엔드포인트(예: timelines, search 등)에 대해 페이지네이션을 사용합니다. 각 API 호출 응답에는 `result_count`, `previous_token`, `next_token`을 포함하는 `meta` 객체가 있습니다. XDK는 `next_token`을 사용하여 여러 API 호출을 처리하므로 개발자는 여러 호출을 하지 않아도 원하는 데이터 양을 지정하기만 하면 됩니다.
SDK는 다음과 같이 이를 단순화합니다:

* **내장 이터레이터**: 원활한 다중 페이지 가져오기를 위해 제너레이터 함수를 사용합니다.
* **명시적 토큰 처리**: 필요할 때 `pagination_token`을 전달하여 유연한 수동 제어가 가능합니다.
* **최대 결과 적용**: 호출당 `max_results`를 준수합니다(API 제한까지, 예: search의 경우 100).

## 자동 페이지네이션 (권장)

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

```python title="Example" lines wrap icon="python" theme={null}
from xdk import Client
client = Client(bearer_token="your_bearer_token")
# Search with automatic pagination
all_posts = []
for page in client.posts.search_recent(
    query="python",
    max_results=100,  # Per page
    tweet_fields=["created_at", "author_id"]  # Optional expansions
):
    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 오류를 피하기 위한 속도 제한 백오프를 지원합니다.

## 수동 페이지네이션

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

```python title="Example" lines wrap icon="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를 사용하는 자세한 코드 예제는 [코드 샘플 GitHub 저장소](https://github.com/xdevplatform/samples/tree/main/python)를 확인하세요.