Pesquisa no X para Marketing: Handles, Datas e Filtros
Nesta página
Transforme o X numa Ferramenta de Monitorização de Marketing
O X (anteriormente Twitter) continua a ser uma das plataformas mais ricas em dados de marketing acionáveis em tempo real. Com a ferramenta x_search na API do Grok, pode consultar esta massa de informação de forma estruturada, filtrada e automatizável, diretamente das suas aplicações ou scripts.
Ao contrário da pesquisa manual no X, a API permite-lhe segmentar contas específicas, períodos e tópicos com precisão. Para um gestor de marketing, isto significa passar de uma monitorização artesanal para um sistema programável de recolha de inteligência competitiva.
Ativar a Pesquisa no X na API do Grok
Ativa a ferramenta x_search declarando-a no array tools do seu pedido à API. Esta funciona exclusivamente na API de Respostas (o endpoint legado de Chat Completions está descontinuado para pesquisa).
from openai import OpenAI
client = OpenAI(
api_key="your-xai-key",
base_url="https://api.x.ai/v1"
)
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What are the latest posts from @nike about their marketing campaigns?",
tools=[{"type": "x_search"}]
)
O modelo decide automaticamente quando lançar uma pesquisa no X com base na sua pergunta. Não precisa de gerir o acionamento manualmente.
Filtrar por Handles: Segmentar Contas Específicas
O parâmetro allowed_x_handles permite-lhe restringir a pesquisa a um máximo de 10 contas específicas do X. Esta é a ferramenta ideal para monitorizar os seus concorrentes diretos ou parceiros.
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Summarize the product announcements from these brands this week",
tools=[{
"type": "x_search",
"allowed_x_handles": [
"nike", "adidas", "puma",
"newbalance", "reebok"
]
}]
)
Por outro lado, o excluded_x_handles permite excluir até 10 contas dos resultados. Nota: estes dois parâmetros são mutuamente exclusivos (não pode combiná-los no mesmo pedido).
Casos de Uso em Marketing
- Monitorização competitiva: acompanhe as 5 a 10 contas dos seus concorrentes diretos
- Parcerias: siga as publicações dos seus parceiros e embaixadores
- Ecossistema: exclua as suas próprias contas para ver apenas o mercado
Filtrar por Datas: Isolar um Período
Os parâmetros from_date e to_date aceitam datas no formato ISO 8601 (AAAA-MM-DD). Isto permite-lhe segmentar uma campanha específica, um evento do setor ou comparar dois períodos.
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Analyze reactions to the Black Friday campaign from these brands",
tools=[{
"type": "x_search",
"allowed_x_handles": ["amazon_fr", "cdiscount", "fnac"],
"from_date": "2025-11-25",
"to_date": "2025-12-02"
}]
)
Esta combinação de handles + datas oferece-lhe um âmbito de pesquisa extremamente preciso, comparável a um brief de estudo de mercado automatizado.
Compreender Imagens e Vídeos de Publicações
Dois parâmetros booleanos enriquecem a sua monitorização visual:
enable_image_understanding: o modelo analisa as imagens contidas nas publicações (visuais de campanha, infografias, capturas de ecrã)enable_video_understanding: o modelo interpreta vídeos (spots publicitários, teasers de produtos, demonstrações)
tools=[{
"type": "x_search",
"allowed_x_handles": ["apple"],
"enable_image_understanding": True,
"enable_video_understanding": True
}]
Para um profissional de marketing, isto significa que o Grok pode descrever os visuais publicitários dos seus concorrentes, identificar códigos de cores utilizados ou resumir o conteúdo de um vídeo promocional, tudo de forma programática.
Prática: Script de Monitorização Semanal
Eis um script completo que gera um relatório de monitorização semanal sobre os seus concorrentes:
from datetime import datetime, timedelta
# Calcular a semana passada
today = datetime.now().strftime("%Y-%m-%d")
last_week = (datetime.now() - timedelta(days=7)).strftime("%Y-%m-%d")
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="""Analyze these brands' posts from the last week.
For each brand, identify:
1. Major product announcements
2. Marketing campaigns launched
3. Tone and positioning used
4. Posts that generated the most engagement""",
tools=[{
"type": "x_search",
"allowed_x_handles": [
"concurrent1", "concurrent2", "concurrent3"
],
"from_date": last_week,
"to_date": today,
"enable_image_understanding": True
}]
)
print(response.output_text)
Pontos-chave
- A Pesquisa no X custa 5 USD por 1.000 chamadas, tornando-a uma ferramenta de monitorização muito acessível
- Pode filtrar por handles (máx. 10) ou datas (formato ISO 8601), ou combinar ambos
allowed_x_handleseexcluded_x_handlessão mutuamente exclusivos- A análise de imagens e vídeos em publicações é exclusiva da Pesquisa no X (não disponível na Pesquisa Web)
- Utilize a API de Respostas (não o Chat Completions, que está descontinuado para pesquisa)