연동 가이드

게시물 조회 연동을 위한 핵심 개념과 모범 사례

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

---

​

인증

모든 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

shellscript

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

shellscript

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

---

​

오류 처리

​

일반적인 오류

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

완전한 엔드포인트 문서

데이터 사전

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

샘플 코드

동작하는 코드 예제

오류 처리

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