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

Pesquisa no X para Marketing: Handles, Datas e Filtros

Aula 1 de 12 Atualizada a 30 de julho de 2026 Intermediario
Nesta página
  1. Transforme o X numa Ferramenta de Monitorização de Marketing
  2. Ativar a Pesquisa no X na API do Grok
  3. Filtrar por Handles: Segmentar Contas Específicas
  4. Filtrar por Datas: Isolar um Período
  5. Compreender Imagens e Vídeos de Publicações
  6. Prática: Script de Monitorização Semanal
  7. Pontos-chave

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.

$5
por 1.000 chamadas
10
handles filtráveis
ISO
formato de data
API
Apenas Respostas

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_handles e excluded_x_handles sã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)