Field

X API v2는 기본적으로 최소한의 데이터를 반환합니다. 각 객체 유형에 대해 추가 데이터를 요청하려면 fields 파라미터를 사용하세요.

Field 작동 방식

기본적으로 post 조회는 id, text, edit_history_tweet_ids만 반환합니다. 더 많은 데이터를 얻으려면 요청에 field 파라미터를 추가하세요:

# Default response - minimal fields
curl "https://api.x.com/2/tweets/1234567890" \
  -H "Authorization: Bearer $TOKEN"

# With additional fields
curl "https://api.x.com/2/tweets/1234567890?tweet.fields=created_at,public_metrics,author_id" \
  -H "Authorization: Bearer $TOKEN"

사용 가능한 field 파라미터

각 객체 유형에는 자체 fields 파라미터가 있습니다:

객체	파라미터	문서
Post (Tweet)	`tweet.fields`	Post field
User	`user.fields`	User field
Media	`media.fields`	Media field
Poll	`poll.fields`	Poll field
Place	`place.fields`	Place field

예시: Post field

tweet.fields로 특정 post field를 요청합니다:

curl "https://api.x.com/2/tweets/1234567890?tweet.fields=created_at,public_metrics,lang" \
  -H "Authorization: Bearer $TOKEN"

응답:

Example response

{
  "data": {
    "id": "1234567890",
    "text": "Hello world!",
    "edit_history_tweet_ids": ["1234567890"],
    "created_at": "2024-01-15T12:00:00.000Z",
    "lang": "en",
    "public_metrics": {
      "retweet_count": 10,
      "reply_count": 5,
      "like_count": 100,
      "quote_count": 2,
      "bookmark_count": 3,
      "impression_count": 1500
    }
  }
}

예시: User field

user.fields로 특정 user field를 요청합니다:

curl "https://api.x.com/2/users/by/username/xdevelopers?user.fields=created_at,description,public_metrics" \
  -H "Authorization: Bearer $TOKEN"

응답:

Example response

{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "xdevelopers",
    "created_at": "2013-12-14T04:35:55.000Z",
    "description": "The voice of the X Developer Platform",
    "public_metrics": {
      "followers_count": 570842,
      "following_count": 2048,
      "tweet_count": 14052,
      "listed_count": 1672
    }
  }
}

관련 객체의 field

관련 객체(예: 게시물의 작성자)에 대한 field를 얻으려면 두 가지가 필요합니다:

관련 객체를 포함하는 expansion
해당 객체 유형에 대한 fields 파라미터

# Get post with author details
curl "https://api.x.com/2/tweets/1234567890?expansions=author_id&user.fields=description,public_metrics" \
  -H "Authorization: Bearer $TOKEN"

응답:

Example response

{
  "data": {
    "id": "1234567890",
    "text": "Hello world!",
    "author_id": "2244994945"
  },
  "includes": {
    "users": [{
      "id": "2244994945",
      "name": "X Developers",
      "username": "xdevelopers",
      "description": "The voice of the X Developer Platform",
      "public_metrics": {
        "followers_count": 570842,
        "following_count": 2048
      }
    }]
  }
}

Expansion에 대해 자세히 알아보기 →

일반적인 field 조합

게시물 분석
사용자 프로필
전체 게시물 컨텍스트
미디어 세부 정보

tweet.fields=created_at,public_metrics,possibly_sensitive

user.fields=created_at,description,location,public_metrics,verified

tweet.fields=created_at,author_id,conversation_id,in_reply_to_user_id,referenced_tweets
expansions=author_id,referenced_tweets.id
user.fields=username,name

tweet.fields=attachments
expansions=attachments.media_keys
media.fields=url,preview_image_url,alt_text,public_metrics

중요 참고 사항

하위 field는 요청할 수 없습니다. public_metrics를 요청하면 모든 지표(좋아요, 재게시, 답글, 인용, 북마크, 노출 수)를 얻습니다. public_metrics.like_count만 요청할 수는 없습니다.

응답의 field 순서는 요청 순서와 다를 수 있습니다
응답에서 누락된 field는 값이 null이거나 비어 있음을 의미합니다
일부 field는 특정 인증이 필요합니다(예: private metrics는 사용자 컨텍스트 필요)
사용 가능한 field는 각 endpoint의 API 레퍼런스를 확인하세요

Getting Started

Products

Fundamentals

Partners & Customers

Resources

Field 작동 방식

사용 가능한 field 파라미터

예시: Post field

예시: User field

관련 객체의 field

일반적인 field 조합

중요 참고 사항

다음 단계

Expansion

Data Dictionary

​Field 작동 방식

​사용 가능한 field 파라미터

​예시: Post field

​예시: User field

​관련 객체의 field

​일반적인 field 조합

​중요 참고 사항

​다음 단계

Expansion

Data Dictionary

Field 작동 방식

사용 가능한 field 파라미터

예시: Post field

예시: User field

관련 객체의 field

일반적인 field 조합

중요 참고 사항

다음 단계