필드

API 응답에서 특정 데이터 필드를 요청합니다

X API v2는 기본적으로 최소한의 데이터만 반환합니다. 각 객체 type에 대해 추가 데이터를 요청하려면 fields 매개변수를 사용하세요.

---

​

필드의 동작 방식

기본적으로 게시물 조회 요청은 id, text, edit_history_tweet_ids만 반환합니다. 더 많은 데이터를 받으려면 요청에 필드 매개변수를 추가하세요:

# 기본 응답 - 최소 필드
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"

---

​

사용 가능한 필드 파라미터

각 객체 유형마다 해당하는 필드 파라미터가 있습니다:

Object	Parameter	Documentation
게시물 (Tweet)	tweet.fields	게시물 필드
사용자	user.fields	사용자 필드
미디어	media.fields	미디어 필드
투표	poll.fields	투표 필드
장소	place.fields	장소 필드

---

​

예시: 게시물 필드

tweet.fields를 사용해 응답에 포함할 특정 게시물 필드를 요청합니다:

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

응답:

{
  "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
    }
  }
}

---

​

예제: 사용자 필드

user.fields를 사용해 특정 사용자 필드를 요청할 수 있습니다:

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

응답:

{
  "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
    }
  }
}

---

​

연관 객체에 대한 필드

연관 객체(예: 게시물 작성자)에 대한 필드를 가져오려면 다음 두 가지가 필요합니다.

1. 연관 객체를 포함하기 위한 expansion
2. 해당 객체 type에 대한 fields 매개변수

# 작성자 세부 정보가 포함된 게시물 가져오기
curl "https://api.x.com/2/tweets/1234567890?expansions=author_id&user.fields=description,public_metrics" \
  -H "Authorization: Bearer $TOKEN"

응답:

{
  "data": {
    "id": "1234567890",
    "text": "Hello world!",
    "author_id": "2244994945"
  },
  "includes": {
    "users": [{
      "id": "2244994945",
      "name": "X Developers",
      "username": "xdevelopers",
      "description": "X 개발자 플랫폼의 공식 계정",
      "public_metrics": {
        "followers_count": 570842,
        "following_count": 2048
      }
    }]
  }
}

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

---

​

자주 사용하는 필드 조합

게시물 분석

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

---

​

중요 참고 사항

하위 필드는 요청할 수 없습니다. public_metrics를 요청하면 모든 메트릭(좋아요, 리포스트, 답글, 인용)이 함께 반환됩니다. public_metrics.like_count만 따로 요청할 수는 없습니다.

• 응답에서 필드 순서는 요청 시의 순서와 다를 수 있습니다
• 응답에 필드가 없다는 것은 해당 값이 null이거나 비어 있다는 의미입니다
• 일부 필드는 특정 인증이 필요합니다(예: 비공개 메트릭은 사용자 컨텍스트가 필요)
• 사용 가능한 필드는 각 엔드포인트의 API 참조 문서를 확인하세요

---

​

다음 단계

Expansions

응답에 관련된 객체를 포함합니다.

데이터 사전

모든 객체에 대한 전체 필드 참조입니다.