> ## 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.
# Expansion
> X API v2 expansion을 사용하여 단일 응답의 includes 섹션에 관련 사용자, 미디어, 투표, 장소 및 참조된 게시물을 포함하세요.
Expansion을 사용하면 단일 API 응답에 관련 객체를 포함할 수 있습니다. 여러 요청을 하지 않고 한 번의 호출로 게시물과 그 작성자, 미디어 또는 참조된 게시물을 가져옵니다.
***
## Expansion 작동 방식
expansion을 요청하면 API는 응답의 `includes` 섹션에 전체 객체를 포함합니다:
```bash theme={null}
curl "https://api.x.com/2/tweets/1234567890?expansions=author_id" \
-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"
}]
}
}
```
`data`의 `author_id`가 `includes`의 user 객체에 연결됩니다.
***
## Post expansion
| Expansion | 반환 값 | 사용 사례 |
| :------------------------------- | :------- | :------------------ |
| `author_id` | User 객체 | 게시물 작성자 세부 정보 가져오기 |
| `referenced_tweets.id` | Post 객체 | 인용/답글 대상 게시물 가져오기 |
| `referenced_tweets.id.author_id` | User 객체 | 참조된 게시물의 작성자 가져오기 |
| `in_reply_to_user_id` | User 객체 | 답글이 달린 사용자 가져오기 |
| `attachments.media_keys` | Media 객체 | 이미지, 동영상, GIF 가져오기 |
| `attachments.poll_ids` | Poll 객체 | 투표 옵션과 표수 가져오기 |
| `geo.place_id` | Place 객체 | 위치 세부 정보 가져오기 |
| `entities.mentions.username` | User 객체 | 언급된 사용자 가져오기 |
| `edit_history_tweet_ids` | Post 객체 | 편집된 게시물의 이전 버전 가져오기 |
***
## User expansion
| Expansion | 반환 값 | 사용 사례 |
| :---------------- | :------ | :--------------- |
| `pinned_tweet_id` | Post 객체 | 사용자의 고정 게시물 가져오기 |
***
## Space expansion
| Expansion | 반환 값 | 사용 사례 |
| :----------------- | :------ | :------------- |
| `creator_id` | User 객체 | Space 생성자 가져오기 |
| `host_ids` | User 객체 | Space 호스트 가져오기 |
| `speaker_ids` | User 객체 | Space 발언자 가져오기 |
| `invited_user_ids` | User 객체 | 초대된 사용자 가져오기 |
***
## DM expansion
| Expansion | 반환 값 | 사용 사례 |
| :----------------------- | :------- | :----------- |
| `sender_id` | User 객체 | 메시지 발신자 가져오기 |
| `participant_ids` | User 객체 | 대화 참가자 가져오기 |
| `attachments.media_keys` | Media 객체 | 첨부된 미디어 가져오기 |
| `referenced_tweets.id` | Post 객체 | 참조된 게시물 가져오기 |
***
## List expansion
| Expansion | 반환 값 | 사용 사례 |
| :--------- | :------ | :----------- |
| `owner_id` | User 객체 | 리스트 소유자 가져오기 |
***
## Field와 결합
Expansion은 각 객체의 기본 field를 반환합니다. 추가 field를 가져오려면 expansion을 field 파라미터와 결합하세요:
```bash theme={null}
curl "https://api.x.com/2/tweets/1234567890?\
expansions=author_id,attachments.media_keys&\
user.fields=description,public_metrics&\
media.fields=url,alt_text" \
-H "Authorization: Bearer $TOKEN"
```
응답:
```json title="Example response" expandable 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": "Check out this image!",
"author_id": "2244994945",
"attachments": {
"media_keys": ["3_1234567890"]
}
},
"includes": {
"users": [{
"id": "2244994945",
"name": "X Developers",
"username": "xdevelopers",
"description": "The voice of the X Developer Platform",
"public_metrics": {
"followers_count": 570842
}
}],
"media": [{
"media_key": "3_1234567890",
"type": "photo",
"url": "https://pbs.twimg.com/media/example.jpg",
"alt_text": "Example image"
}]
}
}
```
***
## 여러 expansion
쉼표로 구분된 목록으로 여러 expansion을 요청합니다:
```bash theme={null}
expansions=author_id,referenced_tweets.id,attachments.media_keys
```
***
## 일반적인 패턴
작성자, 미디어, 참조된 게시물이 포함된 게시물 가져오기:
```bash theme={null}
expansions=author_id,attachments.media_keys,referenced_tweets.id
tweet.fields=created_at,public_metrics,conversation_id
user.fields=username,name,profile_image_url
media.fields=url,preview_image_url,type
```
답글과 그 작성자를 함께 가져오기:
```bash theme={null}
expansions=author_id,in_reply_to_user_id,referenced_tweets.id
tweet.fields=conversation_id,in_reply_to_user_id,created_at
user.fields=username,name
```
사용자 프로필과 고정 게시물을 함께 가져오기:
```bash theme={null}
expansions=pinned_tweet_id
user.fields=description,public_metrics,verified
tweet.fields=created_at,public_metrics
```
***
## data와 includes 연결
`includes`의 객체는 위치 정보를 포함하지 않습니다. ID를 사용하여 연결하세요:
```python theme={null}
# Python example
response = api_call()
post = response["data"]
users = {u["id"]: u for u in response["includes"]["users"]}
# Get the author
author = users.get(post["author_id"])
print(f"{author['name']} said: {post['text']}")
```
```javascript theme={null}
// JavaScript example
const { data: post, includes } = response;
const users = Object.fromEntries(
includes.users.map(u => [u.id, u])
);
const author = users[post.author_id];
console.log(`${author.name} said: ${post.text}`);
```
***
## 다음 단계
각 객체에 대한 특정 field를 요청하세요.
전체 객체 스키마.