> ## 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.

# 통합 가이드

> 이 가이드는 Timelines 엔드포인트를 애플리케이션에 통합할 때 알아야 할 핵심 개념을 다룹니다. timelines를 다루는 X API v2 standard 티어 레퍼런스입니다.

이 가이드는 Timelines 엔드포인트를 애플리케이션에 통합할 때 알아야 할 핵심 개념을 다룹니다.

***

## 인증

### 엔드포인트 요구사항

| Endpoint               | App-Only | User Context |
| :--------------------- | :------- | :----------- |
| User Posts timeline    | ✓        | ✓            |
| User mentions timeline | ✓        | ✓            |
| Home timeline          | —        | ✓ (필수)       |

### 비공개 지표

비공개 지표에 접근하려면 게시물 작성자를 대신해 인증해야 합니다:

<Warning>
  다음 필드는 User Context 인증이 필요합니다:

  * `tweet.fields.non_public_metrics`
  * `tweet.fields.promoted_metrics`
  * `tweet.fields.organic_metrics`
  * `media.fields.non_public_metrics`
  * `media.fields.promoted_metrics`
  * `media.fields.organic_metrics`
</Warning>

***

## Fields 및 expansions

기본적으로 응답에는 `id`, `text`, `edit_history_tweet_ids`만 포함됩니다. 추가 데이터를 요청하세요:

### 예시 요청

<CodeGroup dropdown>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/123/tweets?\
  tweet.fields=created_at,public_metrics,author_id&\
  expansions=author_id,attachments.media_keys&\
  user.fields=username,verified&\
  media.fields=url,type" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Get user's Posts timeline
  for page in client.posts.get_user_posts(
      user_id="123",
      tweet_fields=["created_at", "public_metrics", "author_id"],
      expansions=["author_id", "attachments.media_keys"],
      user_fields=["username", "verified"],
      media_fields=["url", "type"],
      max_results=100
  ):
      for post in page.data:
          print(f"{post.text} - {post.public_metrics}")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Get user's Posts timeline with pagination
  const paginator = client.posts.getUserPosts("123", {
    tweetFields: ["created_at", "public_metrics", "author_id"],
    expansions: ["author_id", "attachments.media_keys"],
    userFields: ["username", "verified"],
    mediaFields: ["url", "type"],
    maxResults: 100,
  });

  for await (const page of paginator) {
    page.data?.forEach((post) => {
      console.log(`${post.text} - ${JSON.stringify(post.public_metrics)}`);
    });
  }
  ```
</CodeGroup>

### 주요 필드

| Field                 | Description              |
| :-------------------- | :----------------------- |
| `created_at`          | 게시물 생성 타임스탬프             |
| `public_metrics`      | 참여 카운트                   |
| `conversation_id`     | 스레드 식별자                  |
| `context_annotations` | 주제 분류                    |
| `entities`            | Hashtags, mentions, URLs |

<Card title="Fields 및 expansions 가이드" icon="sliders" href="/x-api/fundamentals/fields">
  응답 커스터마이징에 대해 자세히 알아보기
</Card>

***

## 페이지네이션

Timeline은 요청당 최대 100개의 게시물을 반환합니다. 더 큰 결과 집합에는 페이지네이션을 사용하세요.

### 동작 방식

1. `max_results`와 함께 초기 요청을 만듭니다
2. `meta` 객체에서 `next_token`을 가져옵니다
3. 다음 요청에 `pagination_token`을 포함시킵니다
4. `next_token`이 반환되지 않을 때까지 반복합니다

### 예시

<CodeGroup dropdown>
  ```bash cURL theme={null}
  # First request
  curl "https://api.x.com/2/users/123/tweets?max_results=100" \
    -H "Authorization: Bearer $BEARER_TOKEN"

  # Subsequent request with pagination token
  curl "https://api.x.com/2/users/123/tweets?max_results=100&pagination_token=NEXT_TOKEN" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python title="Python SDK" lines wrap icon="python" theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # The SDK handles pagination automatically
  all_posts = []

  for page in client.posts.get_user_posts(user_id="123", max_results=100):
      if page.data:
          all_posts.extend(page.data)

  print(f"Found {len(all_posts)} posts")
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  async function getAllTimelinePosts(userId) {
    const allPosts = [];

    // The SDK handles pagination automatically with async iteration
    const paginator = client.posts.getUserPosts(userId, { maxResults: 100 });

    for await (const page of paginator) {
      if (page.data) {
        allPosts.push(...page.data);
      }
    }

    return allPosts;
  }

  // Usage
  const posts = await getAllTimelinePosts("123");
  console.log(`Found ${posts.length} posts`);
  ```
</CodeGroup>

<Card title="페이지네이션 가이드" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" href="/x-api/fundamentals/pagination" width="24" height="24" data-path="icons/xds/icon-arrow-right.svg">
  페이지네이션에 대해 자세히 알아보기
</Card>

***

## 결과 필터링

### 시간 기반 필터링

| Parameter    | Description                 |
| :----------- | :-------------------------- |
| `start_time` | 가장 오래된 게시물 타임스탬프 (ISO 8601) |
| `end_time`   | 가장 최근 게시물 타임스탬프 (ISO 8601)  |
| `since_id`   | 이 ID 이후의 게시물 반환             |
| `until_id`   | 이 ID 이전의 게시물 반환             |

### Exclude 파라미터

결과에서 특정 게시물 유형 제거:

<CodeGroup dropdown>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/users/123/tweets?exclude=retweets,replies" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Exclude retweets and replies
  for page in client.posts.get_user_posts(
      user_id="123",
      exclude=["retweets", "replies"]
  ):
      for post in page.data:
          print(post.text)
  ```

  ```javascript title="JavaScript SDK" lines wrap icon="square-js" theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Exclude retweets and replies
  const paginator = client.posts.getUserPosts("123", {
    exclude: ["retweets", "replies"],
  });

  for await (const page of paginator) {
    page.data?.forEach((post) => console.log(post.text));
  }
  ```
</CodeGroup>

| Value      | Effect |
| :--------- | :----- |
| `retweets` | 리트윗 제외 |
| `replies`  | 답글 제외  |

***

## 볼륨 제한

각 timeline에는 최대 조회 한도가 있습니다:

| Endpoint                     | Maximum Posts |
| :--------------------------- | :------------ |
| User Posts timeline          | 가장 최근 3,200개  |
| User Posts (exclude=replies) | 가장 최근 800개    |
| User mentions timeline       | 가장 최근 800개    |
| Home timeline                | 3,200개 또는 7일  |

<Note>
  이러한 한도를 초과하는 게시물을 요청하면 데이터 없이 성공 응답이 반환됩니다.
</Note>

***

## 게시물 편집

게시물은 30분 이내에 최대 5회까지 편집할 수 있습니다. Timeline 엔드포인트는 항상 가장 최근 버전을 반환합니다.

### 고려 사항

* 30분보다 오래된 게시물은 최종 버전을 나타냅니다
* 거의 실시간 사용 사례에서는 잠재적 편집을 고려해야 합니다
* 필요한 경우 Post lookup으로 최종 상태를 확인하세요

<Card title="게시물 편집 기본" icon="https://mintcdn.com/x-preview/szd6PKNMlRQoyyAo/icons/xds/icon-history.svg?fit=max&auto=format&n=szd6PKNMlRQoyyAo&q=85&s=6afe17587c08ee621e37afde19a07ff1" href="/x-api/fundamentals/edit-posts" width="24" height="24" data-path="icons/xds/icon-history.svg">
  게시물 편집에 대해 자세히 알아보기
</Card>

***

## 게시물 지표

### 공개 지표

App-Only 또는 User Context 인증으로 모든 게시물에 대해 사용할 수 있습니다:

```json theme={null}
{
  "public_metrics": {
    "retweet_count": 156,
    "reply_count": 23,
    "like_count": 892,
    "quote_count": 12,
    "bookmark_count": 34,
    "impression_count": 15200
  }
}
```

### 비공개 지표

게시물 작성자의 User Context 인증이 필요합니다:

* 최근 30일간의 게시물에 대해서만 사용 가능
* 인증된 사용자가 작성한 게시물에 대해서만 반환됨
* 다른 사용자의 게시물에 대해서는 오류 반환

***

## 특수 사례

<Accordion title="비공개 지표와 페이지네이션">
  30일보다 오래된 게시물의 비공개 지표를 요청하면 `result_count: 0`과 함께 `next_token`을 받을 수 있습니다. 이를 피하려면:

  * 요청을 최근 30일 이내로 유지하세요
  * `max_results`를 최소 10 이상으로 사용하세요
</Accordion>

<Accordion title="프로모션되지 않은 게시물의 promoted 지표">
  프로모션되지 않은 게시물의 promoted 지표를 요청하면 빈 응답이 반환됩니다. 알려진 문제입니다.
</Accordion>

<Accordion title="잘린 Retweet 텍스트">
  140자를 초과하는 리트윗의 경우 text 필드가 잘립니다. 전체 텍스트를 얻으려면 `referenced_tweets.id` expansion을 사용하세요.
</Accordion>

***

## 다음 단계

<CardGroup cols={2}>
  <Card title="Home timeline 퀵스타트" icon="house" href="/x-api/posts/timelines/quickstart/reverse-chron-quickstart">
    사용자의 home 피드 가져오기
  </Card>

  <Card title="Mentions 퀵스타트" icon="at" href="/x-api/posts/timelines/quickstart/user-mention-quickstart">
    사용자에 대한 멘션 가져오기
  </Card>

  <Card title="API 레퍼런스" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/users/get-posts" width="24" height="24" data-path="icons/xds/icon-code.svg">
    전체 엔드포인트 문서
  </Card>

  <Card title="페이지네이션" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-arrow-right.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=88e933002782dbdeb204043cedef033e" href="/x-api/fundamentals/pagination" width="24" height="24" data-path="icons/xds/icon-arrow-right.svg">
    큰 결과 집합 처리
  </Card>
</CardGroup>