통합 가이드

이 가이드는 애플리케이션에 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 참조 문서

엔드포인트 전체 문서 보기

페이지네이션

대용량 결과 집합 처리하기

​인증

​엔드포인트 요구 사항

​비공개 지표

​필드와 expansions

​예시 요청

​주요 필드

필드 및 Expansions 가이드

​페이지네이션

​작동 방식

​예시

페이지네이션 가이드

​결과 필터링

​시간 기반 필터링

​제외 매개변수

​볼륨 한도

​게시물 수정

​고려 사항

포스트 편집 기본 사항

​게시물 지표

​공개 메트릭

​비공개 지표

​예외 상황

​다음 단계

홈 타임라인 빠른 시작

멘션 빠른 시작

API 참조 문서

페이지네이션

인증

엔드포인트 요구 사항

비공개 지표

필드와 expansions

예시 요청

주요 필드

페이지네이션

작동 방식

예시

결과 필터링

시간 기반 필터링

제외 매개변수

볼륨 한도

게시물 수정

고려 사항

게시물 지표

공개 메트릭

비공개 지표

예외 상황

다음 단계