Filtragem por Data
Nesta página
Definir a janela temporal de pesquisa
O X Search oferece uma funcionalidade que a Pesquisa Web não tem: a filtragem por data. Pode definir um período específico para limitar os resultados às publicações feitas dentro dessa janela temporal. Esta é uma ferramenta poderosa para análise de tendências, acompanhamento de eventos e monitorização direcionada.
Parâmetros de data
Dois parâmetros controlam a janela temporal:
from_date: data de início da pesquisa (inclusiva)to_date: data de fim da pesquisa (inclusiva)
Ambos são opcionais e independentes. Pode utilizar um sem o outro:
- Apenas
from_date: todas as publicações desde esta data - Apenas
to_date: todas as publicações até esta data - Ambos em conjunto: publicações dentro da janela definida
Formato da data
As datas seguem o formato ISO 8601: YYYY-MM-DD (ano-mês-dia).
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What were the reactions to the Grok 4 launch?",
tools=[{
"type": "x_search",
"from_date": "2026-03-01",
"to_date": "2026-03-31"
}]
)
Esta consulta pesquisa apenas publicações feitas em março de 2026.
Sintaxe do SDK
xAI SDK (Python)
O SDK Python aceita tanto cadeias de caracteres (strings) como objetos datetime:
from xai_sdk.tools import x_search
import datetime
# Utilizando strings
tools=[x_search(
from_date="2026-01-01",
to_date="2026-04-01"
)]
# Utilizando objetos datetime
tools=[x_search(
from_date=datetime.datetime(2026, 1, 1),
to_date=datetime.datetime(2026, 4, 1)
)]
A utilização de objetos datetime é preferível em produção, pois permite calcular datas dinamicamente (por exemplo, “os últimos 7 dias”).
OpenAI SDK (Python)
tools=[{
"type": "x_search",
"from_date": "2026-01-01",
"to_date": "2026-04-01"
}]
Vercel AI SDK (JavaScript)
tools: [xai.tools.xSearch({
fromDate: "2026-01-01",
toDate: "2026-04-01"
})]
Convenção camelCase: fromDate e toDate.
Combinar datas e handles
Combinar a filtragem temporal com a filtragem por handles é particularmente poderoso:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Summarize xAI's announcements this month",
tools=[{
"type": "x_search",
"allowed_x_handles": ["xaboratory", "xaboratorydev"],
"from_date": "2026-04-01",
"to_date": "2026-04-30"
}]
)
Esta consulta combina três filtros: apenas publicações de contas oficiais da xAI e apenas em abril de 2026.
Casos de utilização
Análise de eventos
Acompanhe reações em tempo real durante um evento (conferência, lançamento de produto, anúncio):
# Reações durante uma keynote
tools=[{
"type": "x_search",
"from_date": "2026-03-25",
"to_date": "2026-03-26"
}]
Monitorização semanal automatizada
Crie um relatório de monitorização automático para a semana passada:
from datetime import datetime, timedelta
today = datetime.now()
week_ago = today - timedelta(days=7)
tools=[{
"type": "x_search",
"from_date": week_ago.strftime("%Y-%m-%d"),
"to_date": today.strftime("%Y-%m-%d")
}]
Análise de tendências
Compare discussões sobre um tópico em diferentes períodos, efetuando vários pedidos com janelas temporais distintas.
Melhores práticas
A experiência demonstra que janelas mais curtas funcionam melhor: um período de um a sete dias produz resultados significativamente mais precisos do que um mês inteiro, onde publicações importantes se perdem no volume. Em produção, nunca codifique estas datas diretamente («hardcode»); calcule-as com datetime em cada execução. Caso contrário, a sua janela de «monitorização de 7 dias» consultará sempre a mesma semana desde a implementação. Por fim, a janela temporal define apenas o conjunto de resultados: é o prompt que dita o que fazer com eles. Especifique o que espera — «resumo de tendências», «publicações com maior envolvimento», «anúncios principais» — e o modelo filtrará os resultados em conformidade, em vez de devolver tudo.
Pontos-chave
from_dateeto_dateno formato ISO 8601 (YYYY-MM-DD)- Ambos os parâmetros são opcionais e independentes
- Combine com a filtragem por handles para pesquisas altamente direcionadas
- O SDK Python aceita tanto strings como objetos
datetime - Exclusivo do X Search — a Pesquisa Web não oferece filtragem temporal