연동 가이드

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

인증

모든 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"]
  }
}

사용 가능한 필드

tweet.fields

Field	Description
`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`	답글 허용 범위

user.fields (requires author_id expansion)

Field	Description
`username`	@핸들
`name`	표시 이름
`profile_image_url`	아바타 URL
`verified`	인증 상태
`description`	소개(바이오)
`public_metrics`	팔로워/팔로잉 수
`created_at`	계정 생성 날짜

media.fields (requires attachments.media_keys expansion)

Field	Description
`url`	미디어 URL
`preview_image_url`	썸네일 URL
`type`	photo, 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"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# 추가 필드와 expansions가 포함된 게시물 가져오기
response = client.posts.get(
    "1234567890",
    tweet_fields=["created_at", "public_metrics", "entities"],
    expansions=["author_id", "attachments.media_keys"],
    user_fields=["username", "verified"],
    media_fields=["url", "type"]
)

print(response.data)
print(response.includes)  # 확장된 사용자 및 미디어 객체를 포함

import { Client } from "@xdevplatform/xdk";

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

const response = await client.posts.get("1234567890", {
  tweetFields: ["created_at", "public_metrics", "entities"],
  expansions: ["author_id", "attachments.media_keys"],
  userFields: ["username", "verified"],
  mediaFields: ["url", "type"],
});

console.log(response.data);
console.log(response.includes); // 확장된 사용자 및 미디어 객체를 포함

게시물 수정

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

작동 방식

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

응답 예시

{
  "data": {
    "id": "1234567893",
    "text": "Hello world! (edited twice)",
    "edit_history_tweet_ids": [
      "1234567890",
      "1234567891",
      "1234567893"
    ]
  }
}

30분짜리 편집 가능 시간이 지난 뒤에 조회된 포스트는 최종 버전입니다. 실시간 사용 사례에서는 최근에 게시된 포스트가 아직 수정 중일 수 있다는 점에 유의하세요.

오류 처리

일반적인 오류

Status	Error	Solution
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 참조 문서

완전한 엔드포인트 문서

데이터 사전

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

샘플 코드

동작하는 코드 예제

오류 처리

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