Skip to main content
X API는 풍부한 구조화된 JSON을 반환합니다. 이 사전은 각 객체 유형에 대해 사용 가능한 모든 field를 문서화합니다.

빠른 탐색

전체 상세 field 표 → Data Dictionary Reference

빠른 탐색

특정 field를 요청하려면 fields 파라미터를 사용하고, 관련 객체를 포함하려면 expansions를 사용하세요.

Post (Tweet)

Post는 X에서 핵심 콘텐츠 단위입니다. 각 Post 객체는 텍스트, 메타데이터, 그리고 작성자, 미디어, 투표와 같은 관련 객체에 대한 참조를 포함합니다. 기본 field: id, text, edit_history_tweet_ids 추가 field를 요청하려면 tweet.fields를 사용하고, 관련 객체를 포함하려면 expansions를 사용하세요.

모든 Post field

Tweet Object 조회 샘플 요청 다음 요청에서는 Tweets lookup endpoint에서 Tweet의 field를 요청합니다. $BEARER_TOKEN을 생성한 Bearer Token으로 교체하세요.
샘플 응답
Example response

User

user 객체는 참조된 사용자를 설명하는 Twitter 사용자 계정 메타데이터를 포함합니다. user 객체는 users lookup endpoint에서 반환되는 기본 객체입니다. 이 endpoint에서 추가 user field를 요청하려면 fields 파라미터 user.fields를 사용하세요. user 객체는 Tweet 객체의 자식 객체로도 찾을 수 있으며 expand할 수 있습니다. ?expansions=author_id 또는 ?expansions=in_reply_to_user_id로 확장하여 기본 field만 포함하는 축약된 객체를 얻을 수 있습니다. 객체를 완성하기 위해 추가 field를 요청할 때는 user.fields field 파라미터와 expansion을 함께 사용하세요. user 객체 조회 샘플 요청 다음 요청에서는 users lookup endpoint에서 user의 field를 요청합니다. $BEARER_TOKEN을 생성한 Bearer Token으로 교체하세요.
샘플 응답

Space

Space는 라이브 오디오 대화를 통해 표현과 상호작용을 가능하게 합니다. Space 데이터 사전은 Space에 대한 관련 메타데이터를 포함하며, 모든 세부 정보는 실시간으로 업데이트됩니다. user 객체는 user 리소스에서 찾아 확장할 수 있습니다. 이러한 객체는 expansions 쿼리 파라미터에 host_ids, creator_id, speaker_ids, mentioned_user_ids 중 최소 하나를 추가하여 확장할 수 있습니다. Tweet과 달리 Space는 일시적이며 종료되거나 작성자가 취소하면 사용할 수 없게 됩니다. 앱에서 Space 데이터를 처리할 때는 최신 정보를 반환할 책임이 있으며, 플랫폼에서 더 이상 사용할 수 없는 데이터를 제거해야 합니다. Spaces lookup endpoint를 사용하면 사용자의 기대와 의도를 존중할 수 있습니다. Space 객체 조회 샘플 요청 다음 요청에서는 Spaces lookup endpoint에서 Space의 field를 요청합니다. $BEARER_TOKEN을 생성한 Bearer Token으로 교체하세요.
샘플 응답

List

list 객체는 참조된 List를 설명하는 Twitter Lists 메타데이터를 포함합니다. List 객체는 List lookup endpoint에서 반환되는 기본 객체입니다. 이 endpoint에서 추가 List field를 요청하려면 fields 파라미터 list.fields를 사용하세요. List 객체는 다른 데이터 객체의 자식으로 발견되지 않습니다. 그러나 user 객체는 user 리소스에서 찾아 확장할 수 있습니다. 이러한 객체는 expansions 쿼리 파라미터에 owner_id를 추가하여 확장할 수 있습니다. 기본 List 객체를 완성하기 위해 추가 field를 요청할 때는 list.fields field 파라미터와 이 expansion을 함께 사용하고, expansion 객체를 완성하려면 user.fields를 사용하세요. User 객체 조회 샘플 요청 다음 요청에서는 List lookup by ID endpoint에서 user의 field를 요청합니다. $BEARER_TOKEN을 생성한 Bearer Token으로 교체하세요.
샘플 응답

Media

Media는 Tweet에 첨부된 이미지, GIF 또는 비디오를 의미합니다. media 객체는 어떤 endpoint에서도 기본 객체가 아니지만, Tweet 객체에서 찾아 확장할 수 있습니다. ?expansions=attachments.media_keys로 확장하여 기본 field만 포함하는 축약된 객체를 얻을 수 있습니다. 객체를 완성하기 위해 추가 field를 요청할 때는 media.fields field 파라미터와 expansion을 함께 사용하세요. media 객체 조회 샘플 요청 다음 요청에서는 Tweet lookup endpoint에서 Tweet에 첨부된 media 객체의 field를 요청합니다. media는 Tweet의 자식 객체이므로 attachment.media_keys expansion이 필요합니다. $BEARER_TOKEN을 생성한 Bearer Token으로 교체하세요.

Poll

Tweet에 포함된 투표는 어떤 endpoint에서도 기본 객체가 아니지만, Tweet 객체에서 찾아 확장할 수 있습니다. ?expansions=attachments.poll_ids로 확장하여 기본 field만 포함하는 축약된 객체를 얻을 수 있습니다. 객체를 완성하기 위해 추가 field를 요청할 때는 poll.fields field 파라미터와 expansion을 함께 사용하세요. poll 객체 조회 샘플 요청 다음 요청에서는 Tweets lookup endpoint에서 Tweet에 첨부된 poll 객체의 field를 요청합니다. poll은 Tweet의 자식 객체이므로 attachments.poll_id expansion이 필요합니다. $BEARER_TOKEN을 생성한 Bearer Token으로 교체하세요.
샘플 응답

Place

Tweet에 태그된 장소는 어떤 endpoint에서도 기본 객체가 아니지만, Tweet 리소스에서 찾아 확장할 수 있습니다. ?expansions=geo.place_id로 확장하여 기본 field만 포함하는 축약된 객체를 얻을 수 있습니다. 객체를 완성하기 위해 추가 field를 요청할 때는 place.fields field 파라미터와 expansion을 함께 사용하세요. place 객체 조회 샘플 요청 다음 요청에서는 Tweets lookup endpoint에서 Tweet에 첨부된 place 객체의 field를 요청합니다. place는 Tweet의 자식 객체이므로 geo.place_id expansion이 필요합니다. $BEARER_TOKEN을 생성한 Bearer Token으로 교체하세요.
샘플 응답
Example response

Direct Message 이벤트

Direct Message(DM) 대화는 이벤트로 구성됩니다. X API v2는 현재 세 가지 이벤트 유형을 지원합니다: MessageCreate, ParticipantsJoin, ParticipantsLeave. DM 이벤트 객체는 Direct Message lookup endpoint에서 반환되며, Manage Direct Messages endpoint로 Direct Message가 성공적으로 생성되면 MessageCreate 이벤트가 생성됩니다. DM 이벤트를 요청할 때 세 가지 기본 이벤트 객체 속성(field)이 포함됩니다: id, event_type, text. 추가 이벤트 field를 받으려면 fields 파라미터 dm_event.fields를 사용해 다른 것을 선택하세요. 사용 가능한 다른 이벤트 field는 다음과 같습니다: dm_conversation_id, created_at, sender_id, attachments, participant_ids, referenced_tweets. 이러한 field 중 몇 가지는 Direct Message 이벤트와 관련된 다른 X 객체의 ID를 제공합니다:
  • sender_id - 메시지를 보낸 계정의 ID, 또는 그룹 대화에 참가자를 초대한 계정의 ID
  • partricipants_ids - 계정 ID의 배열. ParticipantsJoin 및 ParticipantsLeave 이벤트의 경우 이 배열은 이벤트를 생성한 계정의 단일 ID를 포함합니다
  • attachments - 발신자가 Twitter에 업로드한 콘텐츠에 대한 미디어 ID를 제공합니다
  • referenced_tweets - text field에서 Tweet URL이 발견되면 해당 Tweet의 ID가 응답에 포함됩니다
이러한 Twitter 객체 ID를 확장하기 위해 sender_id, participant_ids, referenced_tweets.id, attachments.media_keys expansions를 사용할 수 있습니다. Direct Message 이벤트 객체 조회 샘플 요청 이 예시에서는 1:1 대화와 관련된 이벤트를 조회하는 요청을 만들어 봅니다. 이 요청은 기본 Direct Message 이벤트 field와 함께 참조된 Tweet 및 작성자에 대한 추가 field를 반환합니다. 다음을 요청하는 쿼리를 만들어 봅시다:
  • 이벤트가 생성된 시점과 어떤 대화(dm_conversation)에 속하는지 등 기본 이벤트 속성
  • Direct Message를 보낸 계정의 ID와 설명
  • 참조된 Tweet의 텍스트와 게시된 시점
  • 참조된 Tweet 작성자의 계정 ID와 설명
이러한 속성을 반환하려면 요청 쿼리에 다음이 포함됩니다: ?dm_event.fields=id,sender_id,text,created_at,dm_conversation_id&expansions=sender_id,referenced_tweets.id&tweet.fields=created_at,text,author_id&user.fields=description
$BEARER_TOKEN을 생성한 Bearer Token으로 교체하세요. 샘플 응답

Community

Community는 X 사용자가 가장 관심 있는 대화에 더 가까이 다가가고, 연결하고, 공유하는 전용 공간입니다. Community의 Post는 X의 누구나 볼 수 있지만, Community 내부의 다른 사람들만 대화에 참여하고 상호작용할 수 있습니다. Community 객체에는 Community에 대한 관련 메타데이터가 포함됩니다. Community 객체 조회 샘플 요청 다음 요청에서는 제공된 키워드에 기반한 Community 목록을 검색하면서 특정 field를 요청합니다. $BEARER_TOKEN을 생성한 Bearer Token으로 교체하세요.
샘플 응답

전체 field 표와 추가 예시는 Data Dictionary Reference에 있습니다.