Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Filtrar por Perfis no X

Aula 9 de 16 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. Direcionar contas específicas no X
  2. Os dois parâmetros de filtragem
  3. Utilizar allowed_x_handles (lista de permissões)
  4. Utilizar excluded_x_handles (lista de bloqueio)
  5. Sintaxe do SDK
  6. Boas práticas
  7. Pontos-chave

Direcionar contas específicas no X

Assim como a Pesquisa Web permite filtrar por domínios, a Pesquisa no X permite filtrar por contas (perfis). Pode restringir as pesquisas a publicações de um conjunto específico de contas ou excluir determinadas contas dos resultados. Esta filtragem é essencial para casos de uso como monitorização, acompanhamento de marca ou análise de influenciadores.

Os dois parâmetros de filtragem

A Pesquisa no X oferece dois parâmetros de filtragem por perfil:

  • allowed_x_handles: limita a pesquisa às publicações das contas listadas (lista de permissões)
  • excluded_x_handles: exclui as publicações das contas listadas (lista de bloqueio)

Tal como na Pesquisa Web, estes parâmetros são mutuamente exclusivos. Não pode utilizar ambos no mesmo pedido.

Cada parâmetro aceita um array de até 10 perfis (em comparação com 5 domínios na Pesquisa Web).

Utilizar allowed_x_handles (lista de permissões)

Este parâmetro é ideal para monitorizar comunicações de contas específicas:

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What are the latest announcements from xAI?",
    tools=[{
        "type": "x_search",
        "allowed_x_handles": ["xaboratory", "xaboratorydev"]
    }]
)

O modelo apenas pesquisará publicações publicadas por estas contas.

Casos de uso da lista de permissões

  • Inteligência competitiva: monitorizar anúncios dos seus concorrentes
  • Monitorização de marca: acompanhar as suas contas oficiais e as dos seus embaixadores
  • Análise de influenciadores: agregar opiniões de um painel de especialistas
  • Acompanhamento institucional: seguir contas de reguladores ou organizações oficiais

Utilizar excluded_x_handles (lista de bloqueio)

Este parâmetro permite excluir certas contas, como bots ou contas irrelevantes:

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What do developers think about the latest version of Python?",
    tools=[{
        "type": "x_search",
        "excluded_x_handles": ["bot_python_news", "spam_account"]
    }]
)

Casos de uso da lista de bloqueio

  • Excluir bots: remover contas automatizadas dos resultados
  • Excluir spam: filtrar contas conhecidas por conteúdo de baixa qualidade
  • Excluir as suas próprias contas: analisar reações externas sem as suas próprias publicações

Sintaxe do SDK

xAI SDK (Python)

from xai_sdk.tools import x_search

tools=[x_search(
    allowed_x_handles=["elonmusk", "xaboratory"]
)]

OpenAI SDK (Python)

tools=[{
    "type": "x_search",
    "allowed_x_handles": ["elonmusk", "xaboratory"]
}]

Vercel AI SDK (JavaScript)

tools: [xai.tools.xSearch({
  allowedXHandles: ["elonmusk", "xaboratory"]
})]

Note a convenção camelCase no SDK JavaScript: allowedXHandles em vez de allowed_x_handles.

Boas práticas

Escolher entre lista de permissões e lista de bloqueio

Utilize a lista de permissões quando tiver um conjunto definido de contas e quiser apenas as suas publicações. Este é o método mais preciso e eficiente em termos de tokens.

Utilize a lista de bloqueio quando quiser uma pesquisa abrangente, mas precisar de a limpar eliminando fontes de ruído conhecidas.

Otimizar o número de perfis

Com um limite de 10 perfis, seja seletivo. Se precisar de monitorizar mais de 10 contas, agrupe os seus pedidos por tópico ou faça várias chamadas sequenciais.

Formato do perfil

Os perfis não incluem o símbolo @ (por exemplo, xaboratory). Verifique se os perfis estão corretos; um perfil mal escrito simplesmente não devolverá resultados para essa conta.

Pontos-chave

  • Dois parâmetros: allowed_x_handles (lista de permissões) e excluded_x_handles (lista de bloqueio)
  • Mutuamente exclusivos: apenas um de cada vez por pedido
  • Máximo de 10 perfis por parâmetro
  • Os perfis são escritos sem o @: "elonmusk", e não "@elonmusk"
  • Ideal para monitorização, acompanhamento de marca e análise de influenciadores