통합 가이드

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

인증

엔드포인트 요구 사항

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

비공개 지표

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

다음 필드는 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

필드와 expansions

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

예시 요청

cURL

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"

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

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)}`);
  });
}

주요 필드

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

필드 및 Expansions 가이드

응답을 어떻게 사용자 지정할 수 있는지 자세히 알아보세요

페이지네이션

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

작동 방식

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

예시

cURL

# 첫 번째 요청
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"

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)}개의 포스트를 찾았습니다")

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}개의 포스트를 찾았습니다`);

페이지네이션 가이드

페이지네이션에 대해 자세히 알아보기

결과 필터링

시간 기반 필터링

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

제외 매개변수

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

cURL

curl "https://api.x.com/2/users/123/tweets?exclude=retweets,replies" \
  -H "Authorization: Bearer $BEARER_TOKEN"

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)

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));
}

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

볼륨 한도

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

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

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

게시물 수정

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

고려 사항

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

포스트 편집 기본 사항

포스트 편집에 대해 자세히 알아보기

게시물 지표

공개 메트릭

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

{
  "public_metrics": {
    "retweet_count": 156,
    "reply_count": 23,
    "like_count": 892,
    "quote_count": 12
  }
}

비공개 지표

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

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

예외 상황

비공개 메트릭과 페이지네이션

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

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

프로모션되지 않은 포스트의 프로모션 메트릭

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

잘린 리트윗 텍스트

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

다음 단계

홈 타임라인 빠른 시작

사용자의 홈 피드 가져오기

멘션 빠른 시작

사용자의 멘션 가져오기

API 참조 문서

엔드포인트 전체 문서 보기

페이지네이션

대용량 결과 집합 처리하기