Como Definir o Filtro de Recência de Pesquisa na API do Perplexity

Ao consultar a API do Perplexity, o comportamento padrão de pesquisa retorna resultados de qualquer período. Isso pode incluir informações desatualizadas que não são úteis para tarefas que exigem as últimas notícias, eventos recentes ou dados sensíveis ao tempo. O filtro de recência de pesquisa permite restringir os resultados a um intervalo de tempo específico, como o último dia, semana ou mês.

Este artigo explica como configurar o parâmetro de recência em suas requisições à API. Você aprenderá o nome exato do campo JSON, os valores aceitos e como defini-lo usando Python, cURL ou qualquer cliente HTTP. Ao final, você será capaz de controlar a atualidade dos resultados das chamadas à API do Perplexity.

O que o Filtro de Recência de Pesquisa Faz

A API do Perplexity usa um modelo de linguagem online que pesquisa a web em tempo real. Sem um filtro de recência, o modelo recupera o resultado mais autoritativo, independentemente da data de publicação. Isso é adequado para tópicos atemporais, como fatos históricos ou princípios científicos, mas falha para notícias de última hora, preços de ações ou lançamentos recentes de produtos.

O parâmetro search_recency_filter instrui o modelo a priorizar ou restringir os resultados a uma janela de tempo específica. O filtro funciona passando a restrição de tempo para o mecanismo de busca subjacente antes que o modelo processe os resultados. O modelo então gera uma resposta baseada apenas em fontes que atendem ao requisito de recência.

Valores Suportados

O parâmetro aceita quatro valores de string:

• day — restringe os resultados às últimas 24 horas
• week — restringe os resultados aos últimos 7 dias
• month — restringe os resultados aos últimos 30 dias
• any — sem restrição de tempo, equivalente a não definir o filtro

Pré-requisitos

Antes de usar o filtro de recência, certifique-se de ter:

• Uma chave de API do Perplexity válida, obtida no painel da API do Perplexity
• Um cliente HTTP como cURL, Python com a biblioteca requests ou Postman
• Conhecimento de como enviar uma requisição POST para o endpoint da API do Perplexity

Passos para Definir o Filtro de Recência de Pesquisa na Sua Requisição à API

O filtro é definido adicionando um único par chave-valor JSON ao corpo da requisição. A localização exata é importante: o parâmetro deve estar no nível superior do objeto JSON, não dentro do array messages.

Método 1: Usando cURL

1. Abra seu terminal ou prompt de comando
   Certifique-se de que o cURL está instalado no seu sistema. No Windows 10 e Windows 11, você pode usar o PowerShell ou o Prompt de Comando.
2. Componha a requisição POST
   Use o seguinte comando, substituindo YOUR_API_KEY pela sua chave real:
   curl -X POST https://api.perplexity.ai/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "pplx-7b-online", "messages": [{"role": "user", "content": "Quais são as últimas notícias sobre regulação de IA?"}], "search_recency_filter": "week"}'
3. Execute a requisição
   Pressione Enter. A API retornará uma resposta com fontes e texto limitados à última semana.
4. Verifique o filtro na resposta
   Confira se o objeto usage na resposta inclui search_recency_filter definido como week.

Método 2: Usando Python com a Biblioteca Requests

1. Importe a biblioteca requests
   Adicione import requests no topo do seu script Python.
2. Defina o endpoint da API e os cabeçalhos
   url = "https://api.perplexity.ai/chat/completions"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
3. Construa o payload com o filtro de recência
   payload = {
"model": "pplx-7b-online",
"messages": [
{"role": "user", "content": "Quais são as ameaças de cibersegurança mais recentes?"}
],
"search_recency_filter": "day"
}
4. Envie a requisição POST
   response = requests.post(url, headers=headers, json=payload)
print(response.json())
5. Execute o script
   Execute o arquivo Python. A resposta conterá apenas resultados das últimas 24 horas.

Método 3: Usando Postman

1. Crie uma nova requisição POST
   Defina a URL da requisição como https://api.perplexity.ai/chat/completions.
2. Defina o cabeçalho de Autorização
   Adicione um cabeçalho com chave Authorization e valor Bearer YOUR_API_KEY.
3. Defina o cabeçalho Content-Type
   Adicione um cabeçalho com chave Content-Type e valor application/json.
4. Escreva o corpo JSON
   Na aba Body, selecione “raw” e cole:
   {
"model": "pplx-7b-online",
"messages": [
{"role": "user", "content": "Quais são os preços mais recentes das ações de tecnologia?"}
],
"search_recency_filter": "month"
}
5. Envie a requisição
   Clique em Send. A resposta mostrará resultados dos últimos 30 dias.

Erros Comuns e Coisas a Evitar

Filtro Não Aplicado Mesmo com o Parâmetro Definido

Se a API retornar resultados fora do intervalo de tempo especificado, verifique se o parâmetro search_recency_filter está no nível superior do corpo JSON. Colocá-lo dentro do array messages ou aninhado sob outra chave fará com que seja ignorado. Verifique também se o valor da string está em minúsculas e escrito corretamente: day, week, month ou any.

Filtro Funciona com Alguns Modelos, mas Não com Outros

O filtro de recência é suportado em todos os modelos online, mas pode não funcionar em modelos offline que não têm acesso à internet. Certifique-se de usar um nome de modelo que inclua -online em seu identificador, como pplx-7b-online ou mixtral-8x7b-instruct.

Filtro Ignorado Quando a Pesquisa Está Desabilitada

Se você definir "search_domain": false ou omitir o domínio de pesquisa, o modelo não realiza uma pesquisa na web. O filtro de recência não tem efeito porque nenhuma pesquisa é executada. Sempre inclua um domínio de pesquisa ou mantenha o comportamento padrão intacto.

Filtro de Recência de Pesquisa da API do Perplexity: Valores Disponíveis e Efeito

Valor do Filtro	Restrição de Tempo	Caso de Uso
day	Últimas 24 horas	Notícias de última hora, resultados de eventos ao vivo, alertas urgentes
week	Últimos 7 dias	Resumos semanais, análises recentes de produtos, tendências do mercado de ações
month	Últimos 30 dias	Relatórios mensais, mudanças de políticas, atualizações de versões de software
any	Sem restrição	Conteúdo atemporal, fatos históricos, conhecimento fundamental

O filtro de recência é aplicado aos resultados da pesquisa antes de o modelo gerar a resposta. Ele não filtra a data de corte do conhecimento do próprio modelo. Por exemplo, se você perguntar sobre um evento histórico usando search_recency_filter: "day", o modelo ainda usará seus dados de treinamento, mas pesquisará na web apenas artigos recentes sobre esse evento.

Você pode combinar o filtro de recência com outros parâmetros como temperature, max_tokens e search_domain. O filtro não afeta o número de resultados de pesquisa retornados; ele apenas restringe o tempo de publicação.

Agora você pode definir o filtro de recência de pesquisa em qualquer requisição à API do Perplexity para obter respostas limitadas no tempo. Comece testando com o valor week para o melhor equilíbrio entre atualidade e disponibilidade de resultados. Para uma abordagem mais granular, combine o filtro de recência com o parâmetro search_domain para restringir os resultados a um site específico e a um intervalo de tempo simultaneamente.