> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Field
> X API v2는 기본적으로 최소한의 데이터를 반환합니다. 각 객체 유형에 대해 추가 데이터를 요청하려면 fields 파라미터를 사용하세요. 기본적으로 post 조회는 최소한만 반환합니다.
X API v2는 기본적으로 최소한의 데이터를 반환합니다. 각 객체 유형에 대해 추가 데이터를 요청하려면 **fields 파라미터**를 사용하세요.
***
## Field 작동 방식
기본적으로 post 조회는 `id`, `text`, `edit_history_tweet_ids`만 반환합니다. 더 많은 데이터를 얻으려면 요청에 field 파라미터를 추가하세요:
```bash theme={null}
# 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](/x-api/fundamentals/data-dictionary/reference#tweet) |
| User | `user.fields` | [User field](/x-api/fundamentals/data-dictionary/reference#user) |
| Media | `media.fields` | [Media field](/x-api/fundamentals/data-dictionary/reference#media) |
| Poll | `poll.fields` | [Poll field](/x-api/fundamentals/data-dictionary/reference#poll) |
| Place | `place.fields` | [Place field](/x-api/fundamentals/data-dictionary/reference#place) |
***
## 예시: Post field
`tweet.fields`로 특정 post field를 요청합니다:
```bash theme={null}
curl "https://api.x.com/2/tweets/1234567890?tweet.fields=created_at,public_metrics,lang" \
-H "Authorization: Bearer $TOKEN"
```
응답:
```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
"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를 요청합니다:
```bash theme={null}
curl "https://api.x.com/2/users/by/username/xdevelopers?user.fields=created_at,description,public_metrics" \
-H "Authorization: Bearer $TOKEN"
```
응답:
```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
"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를 얻으려면 두 가지가 필요합니다:
1. 관련 객체를 포함하는 **expansion**
2. 해당 객체 유형에 대한 **fields 파라미터**
```bash theme={null}
# 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"
```
응답:
```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
"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에 대해 자세히 알아보기 →](/x-api/fundamentals/expansions)
***
## 일반적인 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 레퍼런스를 확인하세요
***
## 다음 단계
응답에 관련 객체를 포함하세요.
모든 객체에 대한 전체 field 레퍼런스.