메인 콘텐츠로 건너뛰기
이 가이드는 애플리케이션에 Timelines 엔드포인트를 통합하는 데 필요한 핵심 개념을 설명합니다.

​
인증

​
엔드포인트 요구 사항

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

​
비공개 지표

비공개 지표에 액세스하려면 게시물 작성자를 대리하여 인증해야 합니다:
다음 필드는 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"

​
주요 필드

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

필드 및 Expansions 가이드

응답을 어떻게 사용자 지정할 수 있는지 자세히 알아보세요
타임라인은 요청당 최대 100개의 포스트를 반환합니다. 더 많은 결과가 필요하면 페이지네이션을 사용하세요.

​
작동 방식

  1. 초기 요청에서 max_results를 설정합니다.
  2. meta 객체에서 next_token을 가져옵니다.
  3. 다음 요청에 pagination_token을 포함합니다.
  4. 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"

페이지네이션 가이드

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

​
결과 필터링

​
시간 기반 필터링

ParameterDescription
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"
값효과
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 참조 문서

엔드포인트 전체 문서 보기

페이지네이션

대용량 결과 집합 처리하기