Expansions

Expansions permitem incluir objetos relacionados em uma única resposta da API. Em vez de fazer várias solicitações, obtenha um post e seu autor, mídia ou posts referenciados em uma única chamada.

Como as expansions funcionam

Quando você solicita uma expansion, a API inclui o objeto completo na seção includes da resposta:

curl "https://api.x.com/2/tweets/1234567890?expansions=author_id" \
  -H "Authorization: Bearer $TOKEN"

Resposta:

Exemplo de resposta

{
  "data": {
    "id": "1234567890",
    "text": "Hello world!",
    "author_id": "2244994945"
  },
  "includes": {
    "users": [{
      "id": "2244994945",
      "name": "X Developers",
      "username": "xdevelopers"
    }]
  }
}

O author_id em data vincula-se ao objeto user em includes.

Expansions de Post

Expansion	Retorna	Caso de uso
`author_id`	Objeto User	Obter detalhes do autor do post
`referenced_tweets.id`	Objeto(s) Post	Obter posts citados/respondidos
`referenced_tweets.id.author_id`	Objeto(s) User	Obter autores dos posts referenciados
`in_reply_to_user_id`	Objeto User	Obter usuário que está sendo respondido
`attachments.media_keys`	Objeto(s) Media	Obter imagens, vídeos, GIFs
`attachments.poll_ids`	Objeto Poll	Obter opções e votos da enquete
`geo.place_id`	Objeto Place	Obter detalhes de localização
`entities.mentions.username`	Objeto(s) User	Obter usuários mencionados
`edit_history_tweet_ids`	Objeto(s) Post	Obter versões anteriores de posts editados

Expansions de User

Expansion	Retorna	Caso de uso
`pinned_tweet_id`	Objeto Post	Obter o post fixado do usuário

Expansions de Space

Expansion	Retorna	Caso de uso
`creator_id`	Objeto User	Obter criador do Space
`host_ids`	Objeto(s) User	Obter hosts do Space
`speaker_ids`	Objeto(s) User	Obter oradores do Space
`invited_user_ids`	Objeto(s) User	Obter usuários convidados

Expansions de DM

Expansion	Retorna	Caso de uso
`sender_id`	Objeto User	Obter remetente da mensagem
`participant_ids`	Objeto(s) User	Obter participantes da conversa
`attachments.media_keys`	Objeto Media	Obter mídia anexada
`referenced_tweets.id`	Objeto Post	Obter post referenciado

Expansions de List

Expansion	Retorna	Caso de uso
`owner_id`	Objeto User	Obter dono da list

Combinando com fields

Expansions retornam fields padrão para cada objeto. Para obter fields adicionais, combine expansions com parâmetros de field:

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"

Resposta:

Exemplo de resposta

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

Múltiplas expansions

Solicite várias expansions como uma lista separada por vírgulas:

expansions=author_id,referenced_tweets.id,attachments.media_keys

Padrões comuns

Contexto completo do post
Thread de conversa
Usuário com post fixado

Obtenha um post com autor, mídia e posts referenciados:

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

Obtenha respostas com seus autores:

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

Obtenha um perfil de usuário com seu post fixado:

expansions=pinned_tweet_id
user.fields=description,public_metrics,verified
tweet.fields=created_at,public_metrics

Vinculando data e includes

Os objetos em includes não contêm informações de posição. Vincule-os usando IDs:

# 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 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}`);

Getting Started

Products

Fundamentals

Partners & Customers

Resources

Expansions

Como as expansions funcionam

Expansions de Post

Expansions de User

Expansions de Space

Expansions de DM

Expansions de List

Combinando com fields

Múltiplas expansions

Padrões comuns

Vinculando data e includes

Próximos passos

Fields

Dicionário de dados

​Como as expansions funcionam

​Expansions de Post

​Expansions de User

​Expansions de Space

​Expansions de DM

​Expansions de List

​Combinando com fields

​Múltiplas expansions

​Padrões comuns

​Vinculando data e includes

​Próximos passos

Fields

Dicionário de dados

Como as expansions funcionam

Expansions de Post

Expansions de User

Expansions de Space

Expansions de DM

Expansions de List

Combinando com fields

Múltiplas expansions

Padrões comuns

Vinculando data e includes

Próximos passos