메인 콘텐츠로 건너뛰기
이 가이드에서는 애플리케이션에 게시물 조회 엔드포인트를 통합하는 데 필요한 핵심 개념을 다룹니다.

​
인증

모든 X API v2 엔드포인트는 인증이 필요합니다. 사용 사례에 가장 잘 맞는 방식을 선택하세요:
방식최적 용도비공개 메트릭에 접근 가능 여부
OAuth 2.0 App-Only서버 간 통신, 공개 데이터아니요
OAuth 2.0 Authorization Code with PKCE사용자 대상 App예 (인가된 사용자의 포스트)
OAuth 1.0a User Context레거시 통합예 (인가된 사용자의 포스트)

​
App-Only authentication

공개 게시물 데이터를 조회할 때는 Bearer 토큰을 사용합니다:
cURL
curl "https://api.x.com/2/tweets/1234567890" \
  -H "Authorization: Bearer $BEARER_TOKEN"

​
User Context 인증

비공개 메트릭에 접근하려면 게시물 작성자를 대신하여 인증해야 합니다.
다음 필드에는 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

X API v2는 기본적으로 최소한의 데이터만 반환합니다. 정확히 필요한 데이터만 요청하려면 fields와 expansions를 사용하세요.

​
기본 응답

{
  "data": {
    "id": "1234567890",
    "text": "Hello world!",
    "edit_history_tweet_ids": ["1234567890"]
  }
}

​
사용 가능한 필드

FieldDescription
created_at게시물 생성 타임스탬프
author_id작성자의 사용자 ID
public_metrics좋아요, 리포스트, 답글, 인용 횟수
entities해시태그, 멘션, URL, 캐시태그
attachments미디어 키, 투표 ID
conversation_id스레드 식별자
context_annotations토픽/엔터티 분류
in_reply_to_user_id답글 대상 사용자
lang감지된 언어
source게시 클라이언트
possibly_sensitive민감한 콘텐츠 플래그
reply_settings답글 허용 범위
FieldDescription
username@핸들
name표시 이름
profile_image_url아바타 URL
verified인증 상태
description소개(바이오)
public_metrics팔로워/팔로잉 수
created_at계정 생성 날짜
FieldDescription
url미디어 URL
preview_image_url썸네일 URL
typephoto, video, animated_gif
duration_ms동영상 길이
height, width크기
alt_text접근성 텍스트

​
필드가 포함된 예시

cURL
curl "https://api.x.com/2/tweets/1234567890?\
tweet.fields=created_at,public_metrics,entities&\
expansions=author_id,attachments.media_keys&\
user.fields=username,verified&\
media.fields=url,type" \
  -H "Authorization: Bearer $BEARER_TOKEN"

​
게시물 수정

게시물은 작성 후 30분 이내에 최대 5번까지 수정할 수 있습니다.

​
작동 방식

  • 각 편집 시 새로운 게시물 ID가 생성됩니다
  • edit_history_tweet_ids에는 모든 버전이 포함되며, 가장 오래된 것부터 나열됩니다
  • 이 엔드포인트에서는 항상 최신 버전을 반환합니다

​
응답 예시

{
  "data": {
    "id": "1234567893",
    "text": "Hello world! (edited twice)",
    "edit_history_tweet_ids": [
      "1234567890",
      "1234567891",
      "1234567893"
    ]
  }
}
30분짜리 편집 가능 시간이 지난 뒤에 조회된 포스트는 최종 버전입니다. 실시간 사용 사례에서는 최근에 게시된 포스트가 아직 수정 중일 수 있다는 점에 유의하세요.

​
오류 처리

​
일반적인 오류

StatusErrorSolution
400잘못된 요청매개변수 형식을 확인하세요
401인증 실패인증 정보를 확인하세요
403액세스 거부App 권한을 확인하세요
404찾을 수 없음게시물이 삭제되었거나 존재하지 않습니다
429요청이 너무 많습니다잠시 기다렸다가 다시 시도하세요 (요청 한도 참고)

​
삭제되었거나 보호된 포스트

게시물이 삭제되었거나, 사용자가 팔로우하지 않는 보호된 계정의 게시물인 경우:
  • 단일 게시물 조회에서는 404를 반환합니다.
  • 다중 게시물 조회에서는 결과에서 해당 게시물을 제외하고 errors 배열을 포함합니다.
{
  "data": [
    { "id": "1234567890", "text": "Available post" }
  ],
  "errors": [
    {
      "resource_id": "1234567891",
      "resource_type": "tweet",
      "title": "Not Found Error",
      "detail": "Could not find tweet with id: [1234567891]."
    }
  ]
}

​
모범 사례

요청 일괄 처리

multi-Post endpoint를 사용해 한 번에 최대 100개의 게시물을 가져와 API 호출을 줄이세요.

필요한 필드만 요청

응답 크기와 처리 시간을 최소화하기 위해 필요한 필드만 지정하세요.

응답 캐싱

동일한 콘텐츠에 대한 반복 요청을 줄이기 위해 게시물 데이터를 로컬에 캐싱하세요.

수정 처리

실시간 앱의 경우 30분 편집 가능 시간이 지난 후에 게시물을 다시 조회하는 것을 고려하세요.

​
다음 단계

API 참조 문서

완전한 엔드포인트 문서

데이터 사전

사용 가능한 모든 객체와 필드

샘플 코드

동작하는 코드 예제

오류 처리

오류를 안정적으로 처리하는 방법