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

# 통합 가이드

> Timelines 엔드포인트를 통합하기 위한 핵심 개념과 모범 사례

이 가이드는 애플리케이션에 Timelines 엔드포인트를 통합하는 데 필요한 핵심 개념을 설명합니다.

***

<div id="authentication">
  ## 인증
</div>

<div id="endpoint-requirements">
  ### 엔드포인트 요구 사항
</div>

| Endpoint     | App 전용 | 사용자 컨텍스트 |
| :----------- | :----- | :------- |
| 사용자 포스트 타임라인 | ✓      | ✓        |
| 사용자 멘션 타임라인  | ✓      | ✓        |
| 홈 타임라인       | —      | ✓ (필수)   |

<div id="private-metrics">
  ### 비공개 지표
</div>

비공개 지표에 액세스하려면 게시물 작성자를 대리하여 인증해야 합니다:

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

***

<div id="fields-and-expansions">
  ## 필드와 expansions
</div>

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

<div id="example-request">
  ### 예시 요청
</div>

<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 Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # 사용자의 포스트 타임라인 가져오기
  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 JavaScript SDK theme={null}
  import { Client } from "@xdevplatform/xdk";

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

  // 페이지네이션을 사용해 사용자의 포스트 타임라인 가져오기
  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>

<div id="key-fields">
  ### 주요 필드
</div>

| 필드                    | 설명            |
| :-------------------- | :------------ |
| `created_at`          | 게시물 생성 시각     |
| `public_metrics`      | 참여 지표         |
| `conversation_id`     | 스레드 식별자       |
| `context_annotations` | 주제 분류 정보      |
| `entities`            | 해시태그, 멘션, URL |

<Card title="필드 및 Expansions 가이드" icon="sliders" href="/ko/x-api/fundamentals/fields">
  응답을 어떻게 사용자 지정할 수 있는지 자세히 알아보세요
</Card>

***

<div id="pagination">
  ## 페이지네이션
</div>

타임라인은 요청당 최대 100개의 포스트를 반환합니다. 더 많은 결과가 필요하면 페이지네이션을 사용하세요.

<div id="how-it-works">
  ### 작동 방식
</div>

1. 초기 요청에서 `max_results`를 설정합니다.
2. `meta` 객체에서 `next_token`을 가져옵니다.
3. 다음 요청에 `pagination_token`을 포함합니다.
4. `next_token`이 더 이상 반환되지 않을 때까지 반복합니다.

<div id="example">
  ### 예시
</div>

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

  # 페이지네이션 토큰을 포함한 다음 요청
  curl "https://api.x.com/2/users/123/tweets?max_results=100&pagination_token=NEXT_TOKEN" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

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

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # SDK가 페이지네이션을 자동으로 처리합니다
  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"{len(all_posts)}개의 포스트를 찾았습니다")
  ```

  ```javascript JavaScript SDK theme={null}
  import { Client } from "@xdevplatform/xdk";

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

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

    // SDK가 비동기 반복을 통해 페이지네이션을 자동으로 처리합니다
    const paginator = client.posts.getUserPosts(userId, { maxResults: 100 });

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

    return allPosts;
  }

  // 사용 예시
  const posts = await getAllTimelinePosts("123");
  console.log(`총 ${posts.length}개의 포스트를 찾았습니다`);
  ```
</CodeGroup>

<Card title="페이지네이션 가이드" icon="arrow-right" href="/ko/x-api/fundamentals/pagination">
  페이지네이션에 대해 자세히 알아보기
</Card>

***

<div id="filtering-results">
  ## 결과 필터링
</div>

<div id="time-based-filtering">
  ### 시간 기반 필터링
</div>

| Parameter    | Description                  |
| :----------- | :--------------------------- |
| `start_time` | 가장 오래된 게시물의 타임스탬프 (ISO 8601) |
| `end_time`   | 가장 최신 게시물의 타임스탬프 (ISO 8601)  |
| `since_id`   | 이 id 이후의 포스트를 반환합니다          |
| `until_id`   | 이 id 이전의 포스트를 반환합니다          |

<div id="exclude-parameter">
  ### 제외 매개변수
</div>

결과에서 특정 게시물 유형을 제외합니다:

<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")

  # 리트윗과 답글 제외
  for page in client.posts.get_user_posts(
      user_id="123",
      exclude=["retweets", "replies"]
  ):
      for post in page.data:
          print(post.text)
  ```

  ```javascript JavaScript SDK theme={null}
  import { Client } from "@xdevplatform/xdk";

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

  // 리트윗과 답글 제외
  const paginator = client.posts.getUserPosts("123", {
    exclude: ["retweets", "replies"],
  });

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

| 값          | 효과     |
| :--------- | :----- |
| `retweets` | 리트윗 제외 |
| `replies`  | 답글 제외  |

***

<div id="volume-limits">
  ## 볼륨 한도
</div>

각 타임라인에는 최대 조회 한도가 있습니다:

| Endpoint                     | 최대 포스트 수            |
| :--------------------------- | :------------------ |
| User Posts timeline          | 최근 3,200개           |
| User Posts (exclude=replies) | 최근 800개             |
| User mentions timeline       | 최근 800개             |
| Home timeline                | 최근 3,200개 또는 최근 7일치 |

<Note>
  이 한도를 초과하여 포스트를 요청하면 데이터가 없는 성공 응답이 반환됩니다.
</Note>

***

<div id="post-edits">
  ## 게시물 수정
</div>

게시물은 30분 이내에 최대 5번까지 수정할 수 있습니다. 타임라인 엔드포인트는 항상 게시물의 최신 버전을 반환합니다.

<div id="considerations">
  ### 고려 사항
</div>

* 30분이 지난 포스트는 최종 버전으로 간주됩니다
* 준 실시간 사용 사례에서는 포스트가 수정될 수 있음을 고려해야 합니다
* 필요한 경우 Post 조회를 사용해 최종 상태를 확인하세요

<Card title="포스트 편집 기본 사항" icon="clock-rotate-left" href="/ko/x-api/fundamentals/edit-posts">
  포스트 편집에 대해 자세히 알아보기
</Card>

***

<div id="post-metrics">
  ## 게시물 지표
</div>

<div id="public-metrics">
  ### 공개 메트릭
</div>

App-Only 또는 User Context 인증으로 접근하는 모든 포스트에 대해 제공됩니다:

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

<div id="private-metrics">
  ### 비공개 지표
</div>

포스트 작성자의 User Context 인증이 필요합니다.

* 최근 30일 이내의 포스트에만 사용할 수 있습니다
* 인증된 사용자가 작성한 포스트에 대해서만 반환됩니다
* 다른 사용자의 포스트에 대해서는 오류가 반환됩니다

***

<div id="edge-cases">
  ## 예외 상황
</div>

<Accordion title="비공개 메트릭과 페이지네이션">
  30일이 지난 포스트에 대한 비공개 메트릭을 요청할 때 `result_count: 0`과 함께 `next_token`을 받을 수 있습니다. 이를 피하려면:

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

<Accordion title="프로모션되지 않은 포스트의 프로모션 메트릭">
  프로모션되지 않은 포스트에 대해 프로모션 메트릭을 요청하면 빈 응답이 반환됩니다. 이는 알려진 문제입니다.
</Accordion>

<Accordion title="잘린 리트윗 텍스트">
  텍스트가 140자를 초과하는 리트윗의 경우, `text` 필드는 잘려서 반환됩니다. 전체 텍스트를 가져오려면 `referenced_tweets.id` 확장을 사용하세요.
</Accordion>

***

<div id="next-steps">
  ## 다음 단계
</div>

<CardGroup cols={2}>
  <Card title="홈 타임라인 빠른 시작" icon="house" href="/ko/x-api/posts/timelines/quickstart/reverse-chron-quickstart">
    사용자의 홈 피드 가져오기
  </Card>

  <Card title="멘션 빠른 시작" icon="at" href="/ko/x-api/posts/timelines/quickstart/user-mention-quickstart">
    사용자의 멘션 가져오기
  </Card>

  <Card title="API 참조 문서" icon="code" href="/ko/x-api/posts/user-posts-timeline-by-user-id">
    엔드포인트 전체 문서 보기
  </Card>

  <Card title="페이지네이션" icon="arrow-right" href="/ko/x-api/fundamentals/pagination">
    대용량 결과 집합 처리하기
  </Card>
</CardGroup>