Salta al contenuto principale

03 - Search API di Perplexity per la tua RAG

La Search API di Perplexity restituisce pagine, non risposte: parametri, costo per richiesta, limite per query e come controllare in locale le citazioni.

Cosa ne pensi di questo articolo?

03 - Search API di Perplexity per la tua RAG
Perplexityfedericocalo.dev

In Breve

La Search API di Perplexity restituisce pagine, non risposte: parametri, costo per richiesta, limite per query e come controllare in locale le citazioni.

Risposta diretta. La Search API di Perplexity è un solo endpoint (POST https://api.perplexity.ai/search) che restituisce risultati web ordinati, ciascuno con title, url, date, last_updated e uno snippet che contiene il testo estratto dalla pagina, e nessun testo generato. Costa 5,00 dollari ogni mille richieste riuscite (1,00 con search_type: "fast") e una richiesta con fino a cinque query si fattura come una sola. È la scelta giusta quando hai già un modello e vuoi decidere tu quali fonti entrano nel prompt, come le mostri e quante ne tieni. Il suo limite principale: ti consegna pagine, non fatti verificati.

Parametri, limiti e prezzi vengono dalle pagine «Search API quickstart», «Pricing», «Rate limits & usage tiers» e «Date & Time Filters» aperte il 13 novembre 2026. Non ho una chiave e non ho chiamato il servizio: gli esempi di risultato in questo articolo sono costruiti da me nella forma documentata, con contenuto inventato, e gli script girano senza rete su pagine HTML di prova. Quello che il servizio restituisce davvero lo vedrai solo con la tua chiave.

La richiesta, parametro per parametro

ParametroTipoCosa fa (documentazione)
querystringa o arrayCon un array, fino a cinque query correlate, ognuna elaborata in modo indipendente
max_resultsinteroDa 1 a 20, predefinito 10
max_tokensinteroTetto del contenuto di pagina sull'insieme dei risultati, fino a 1.000.000
max_tokens_per_pageinteroTetto per ciascuna pagina
countrystringaCodice ISO 3166-1 alpha-2 (IT, DE, ...) per risultati più pertinenti a un paese
search_domain_filterarrayFino a 20 domini o percorsi; senza prefisso è lista consentita, con - lista negata; le due modalità non si combinano
search_language_filterarrayCodici ISO 639-1, fino a 20
search_after_date_filter, search_before_date_filterstringaIntervallo sulla data di pubblicazione, formato mese/giorno/anno (la pagina scrive %m/%d/%Y, con esempio 3/1/2025)
last_updated_after_filter, last_updated_before_filterstringaIntervallo sulla data di ultima modifica, stesso formato
search_recency_filterstringahour, day, week, month, year, relativi a oggi
search_typestringa"fast" per latenza e costo ridotti; richiede SDK Python 0.43.6 o successivo, TypeScript 0.38.6 o successivo

Nella risposta, accanto all'identificativo della richiesta, c'è l'elenco results. Due conseguenze pratiche, entrambe visibili negli esempi della documentazione: lo snippet può essere una stringa vuota e date può essere null, quindi il tuo codice deve gestirli. E la data non è una garanzia di freschezza: è un dato che la pagina o il motore espone, quando lo espone, e i filtri di data lavorano su quel dato. La pagina avverte anche che i campi dell'Agent API (model, effort, instructions, tools, max_output_tokens) non fanno parte di una richiesta di ricerca.

Con una chiave, la chiamata ha questa forma (schema da adattare, non eseguito: la forma è quella del quickstart, i valori sono miei):

from perplexity import Perplexity

client = Perplexity()  # legge PERPLEXITY_API_KEY dall'ambiente

ricerca = client.search.create(
    query=["file robots.txt e crawler", "robots.txt regole per i crawler di assistenti"],
    max_results=8,
    max_tokens_per_page=1500,
    country="IT",
    search_language_filter=["it"],
    search_domain_filter=["developers.google.com", "rfc-editor.org"],
)
for r in ricerca.results:
    print(r.title, r.url)

Le due query nell'array contano come una richiesta fatturata e come due unità di limite di frequenza. max_tokens_per_page limita quanto testo viene estratto da ogni pagina, e la pagina «Pricing» precisa che la quantità di testo estratto non cambia il prezzo: è una leva sulla dimensione del tuo prompt, non sul conto. I due domini nella lista consentita sono un esempio scelto da me; ricorda che con una lista consentita escludi tutto il resto del web, inclusa la pagina che ti serviva.

Cercare, pulire, citare: la parte che esegui in locale

Lo schema di una pipeline RAG con fonti verificabili ha tre passi tuoi: pulire i risultati, far rispondere il tuo modello citando solo gli identificativi che gli hai dato, controllare in codice le citazioni. La parte che puoi provare senza chiave e senza modello è la prima e la terza, e lo script che segue lo fa su risultati sintetici nella forma documentata (contenuto inventato). Al posto della risposta del modello c'è una stringa fissa, scritta da me con una citazione sbagliata apposta; al posto della rete, due pagine HTML create in una cartella temporanea.

"""Pulizia dei risultati e controllo delle citazioni, senza rete e senza modello."""
import re
import tempfile
from html import unescape
from pathlib import Path
from urllib.parse import urlsplit, urlunsplit

# Risultati SINTETICI nella forma documentata (title, url, snippet, date): contenuto inventato.
RISULTATI = [
    {"title": "Guida ai crawler", "url": "https://Esempio.test/guida/?utm_source=x#sec", "snippet": "Il file robots.txt sta nella radice.", "date": "2026-05-01"},
    {"title": "Guida ai crawler (copia)", "url": "https://esempio.test/guida", "snippet": "Il file robots.txt sta nella radice.", "date": None},
    {"title": "Pagina senza testo", "url": "https://esempio.test/vuota", "snippet": "", "date": None},
    {"title": "Note sul traffico", "url": "https://esempio.test/note", "snippet": "Il traffico di un utente si distingue.", "date": "2026-03-02"},
]
# Cio' che direbbe il modello: stringa fissa, NON generata. Una citazione e' scritta male apposta.
RISPOSTA = ("«il file robots.txt sta nella radice» [1] e «ogni crawler obbedisce sempre» [2]. "
            "Un terzo punto cita una fonte che non c'e' [9].")


def normalizza(url: str) -> str:
    p = urlsplit(url)
    query = "&".join(q for q in p.query.split("&") if q and not q.startswith("utm_"))
    return urlunsplit((p.scheme, p.netloc.lower(), p.path.rstrip("/") or "/", query, ""))


def pulisci(risultati):
    visti, puliti = set(), []
    for r in risultati:
        chiave = normalizza(r["url"])
        if chiave in visti or not r["snippet"].strip():
            continue
        visti.add(chiave)
        puliti.append({**r, "url": chiave})
    return puliti


def testo_pagina(html: str) -> str:
    senza_tag = re.sub(r"<[^>]+>", " ", html)
    return re.sub(r"\s+", " ", unescape(senza_tag)).casefold()


def verifica(risposta: str, fonti, cartella: Path):
    esiti = []
    for frase, n in re.findall(r"«([^»]+)»\s*\[(\d+)\]", risposta):
        n = int(n)
        if not 1 <= n <= len(fonti):
            esiti.append((n, "FONTE INESISTENTE"))
            continue
        file = cartella / (urlsplit(fonti[n - 1]["url"]).path.strip("/") + ".html")
        if not file.exists():
            esiti.append((n, "PAGINA NON RAGGIUNGIBILE"))
        elif frase.casefold() in testo_pagina(file.read_text(encoding="utf-8")):
            esiti.append((n, "frase trovata nella pagina"))
        else:
            esiti.append((n, "FRASE ASSENTE DALLA PAGINA"))
    for n in re.findall(r"\[(\d+)\]", risposta):
        if not 1 <= int(n) <= len(fonti):
            esiti.append((int(n), "FONTE INESISTENTE"))
    return esiti


fonti = pulisci(RISULTATI)
print(len(RISULTATI), "risultati ->", len(fonti), "dopo la pulizia")
with tempfile.TemporaryDirectory() as d:
    cartella = Path(d)
    # Pagine di prova locali: la 1 contiene la frase citata, la 2 no.
    (cartella / "guida.html").write_text("<p>Il file <b>robots.txt</b> sta nella\nradice del sito.</p>", encoding="utf-8")
    (cartella / "note.html").write_text("<p>Alcuni crawler ignorano le regole.</p>", encoding="utf-8")
    for n, esito in verifica(RISPOSTA, fonti, cartella):
        print(f"[{n}] {esito}")

# Output:
# 4 risultati -> 2 dopo la pulizia
# [1] frase trovata nella pagina
# [2] FRASE ASSENTE DALLA PAGINA
# [9] FONTE INESISTENTE

Il codice è stato eseguito due volte con uscita identica (Python 3.14, solo libreria standard). normalizza porta l'indirizzo a una forma confrontabile (host in minuscolo, niente frammento, niente parametri utm_, niente barra finale) e pulisci scarta i duplicati e i risultati con snippet vuoto: da quattro risultati ne restano due. Questa pulizia ha un prezzo che conviene sapere: scartare lo snippet vuoto elimina anche pagine che potrebbero servire, e la documentazione mostra risultati con snippet vuoto accanto ad altri pieni; in produzione puoi scegliere di scaricare quelle pagine invece di buttarle. La normalizzazione, poi, considera uguali due indirizzi che alcuni siti trattano come diversi.

verifica cerca nella risposta le frasi fra virgolette caporali seguite da un numero e controlla che la frase compaia nel testo della pagina corrispondente, dopo aver tolto i tag e normalizzato spazi e maiuscole. L'uscita ha i tre esiti che interessano: la frase 1 è nella pagina; la frase 2 cita una fonte che esiste ma non contiene quelle parole; il riferimento 9 non corrisponde a nessun risultato. Il controllo regge solo per le citazioni testuali: una parafrasi corretta fallirebbe, e una frase presente nella pagina in un contesto diverso passerebbe. Per le affermazioni parafrasate servono un campione letto da una persona o un secondo passaggio di verifica, e per questo conviene decidere in anticipo dove sbagliare costa (contratti, norme, salute) e lì tenere sempre una lettura umana.

Tre limiti di questo schema vanno dichiarati. Le pagine di prova sono file locali, non risposte della rete: in produzione scaricheresti la pagina, rispettando i suoi termini d'uso e il suo robots.txt, e dovresti gestire pagine che cambiano, richiedono JavaScript o rispondono con errori. Lo script non dimostra che il modello obbedisca all'istruzione di citare fra virgolette: va chiesto nel prompt e controllato su un campione. E «frase presente nella pagina» non vuol dire «pagina autorevole»: la scelta delle fonti, con la lista consentita dei domini, resta una decisione tua.

Cinque query in una richiesta: il conto vero

Un array di query è conveniente perché si fattura come una richiesta. Ma il limite di frequenza conta ogni query: dalla pagina dei limiti, POST /search ammette 50 unità al secondo con raffica di 50, indipendentemente dal livello di utilizzo dell'account, e una richiesta a cinque query consuma cinque unità. Il vantaggio economico c'è, quello sul limite no, e con un carico alto i 429 arrivano prima di quanto suggerisca la fattura. Lo script mette a confronto le due unità.

"""Fatturazione e limite di frequenza della Search API: due unita' diverse."""
import math

LIMITE_UNITA_AL_SECONDO = 50  # POST /search, raffica 50: pagina "Rate limits & usage tiers"
PREZZO_PER_MILLE = {"web": 5.00, "fast": 1.00}  # pagina "Pricing"


def conto(richieste: int, query_per_richiesta: int, tipo: str):
    costo = richieste / 1000 * PREZZO_PER_MILLE[tipo]
    unita_limite = richieste * query_per_richiesta
    # Dopo la raffica iniziale da 50, il ritmo sostenuto e' 50 unita' al secondo.
    secondi_minimi = max(0, math.ceil((unita_limite - LIMITE_UNITA_AL_SECONDO) / LIMITE_UNITA_AL_SECONDO))
    return costo, unita_limite, secondi_minimi


def secondi_simulati(unita: int) -> int:
    """Secondo metodo: secchio da 50 gettoni che si riempie di 50 al secondo, a passi di un secondo."""
    gettoni, t, restanti = LIMITE_UNITA_AL_SECONDO, 0, unita
    while restanti > 0:
        presi = min(gettoni, restanti)
        restanti -= presi
        gettoni -= presi
        if restanti > 0:
            t += 1
            gettoni = LIMITE_UNITA_AL_SECONDO
    return t


print(f"{'richieste':>9} {'query':>5} {'tipo':>4} {'costo $':>8} {'unita':>6} {'secondi min':>11}")
for r, q, tipo in [(1, 1, "web"), (1, 5, "web"), (10_000, 1, "web"), (60, 5, "fast"), (1_800, 5, "fast")]:
    costo, unita, sec = conto(r, q, tipo)
    assert sec == secondi_simulati(unita), (r, q, sec, secondi_simulati(unita))
    print(f"{r:>9} {q:>5} {tipo:>4} {costo:>8.3f} {unita:>6} {sec:>11}")
print("formula e simulazione concordano su ogni riga")

# Output:
# richieste query tipo  costo $  unita secondi min
#         1     1  web    0.005      1           0
#         1     5  web    0.005      5           0
#     10000     1  web   50.000  10000         199
#        60     5 fast    0.060    300           5
#      1800     5 fast    1.800   9000         179
# formula e simulazione concordano su ogni riga

Le prime due righe mostrano la differenza: una richiesta da cinque query costa quanto una da una (0,005 dollari), ma occupa cinque unità del limite. L'ultima colonna è una stima dalla descrizione della pagina (raffica da 50, poi 50 al secondo di media): 10.000 richieste a una query ciascuna, spedite il più in fretta possibile, richiedono almeno 199 secondi. Lo stesso numero esce da due modelli diversi, una formula chiusa e una simulazione a passi di un secondo con un secchio da 50 gettoni; sono due calcoli miei sulla stessa descrizione, non una misura del sistema reale, che usa un algoritmo di cui la pagina dà solo il nome (leaky bucket). Le righe da 60 e da 1.800 richieste da cinque query corrispondono a un'ipotesi che uso nello scenario qui sotto.

Uno scenario dichiarato: sorvegliare sessanta temi ogni giorno

Scenario ipotetico, con numeri scelti da me per dare un dominio al conto. Una centrale operativa vuole tenere d'occhio sessanta argomenti (per esempio tratte e valichi) e ogni mattina manda una richiesta per argomento, ciascuna con cinque query (sciopero, chiusura, meteo, ritardi, dogana), in modalità fast. Sono 60 richieste al giorno, 1.800 al mese: 1,80 dollari al mese di Search API (la riga dello script), 300 unità di limite al giorno, che non preoccupano nessun limite da 50 al secondo.

Il conto è l'ultima delle preoccupazioni. Cosa va storto: i falsi negativi (la notizia che il motore non ha ancora indicizzato) e le date mancanti. Una decisione di instradamento che costa denaro non si basa su uno snippet: il sistema produce un elenco di segnalazioni con link, una persona le conferma sulla fonte ufficiale, e la ricerca generica resta un complemento: le fonti con un feed proprio vanno interrogate direttamente, e l'assenza di un risultato non prova l'assenza di una notizia.

Quando la Search API non è la risposta

  • Dati interni. Documenti aziendali, ticket, listini non sono sul web: qui serve il tuo indice (embeddings più un archivio di vettori).
  • Garanzie contrattuali sui dati. La pagina «Privacy & Security» dice che conservazione, uso e sicurezza variano per API, modello e configurazione dell'account, e precisa le limitazioni di modello della Zero Data Retention solo per gli account dell'Agent API; per la Search API non dice nulla di esplicito. Se hai impegni contrattuali, chiedilo per iscritto (articolo 1).
  • Risposta pronta senza costruire nulla. Se non hai un modello né una pipeline, l'Agent API (articolo 2) fa più strada con meno codice, accettando un costo variabile.

I tre casi hanno in comune la stessa domanda: che cosa ti serve che il servizio non fa. La Search API fa una cosa sola, recuperare pagine; tutto ciò che viene dopo (leggere, sintetizzare, citare, garantire) è codice tuo o un altro prodotto, e conviene accorgersene prima di cominciare, non dopo il primo mese di lavoro.

Che cosa sai fare adesso

Sai scrivere una richiesta alla Search API con i parametri giusti e sai quali campi dell'Agent API non ci vanno. Sai pulire un elenco di risultati e controllare in locale che le frasi citate esistano nella pagina, e sai dove questo controllo smette di bastare. Sai distinguere l'unità di fatturazione dall'unità di limite e stimare quanto tempo richiede un lotto di richieste. Il passo successivo, se hai già codice su Sonar, è l'articolo 4.

← Articolo 2: l'Agent API Articolo 4: da Sonar all'Agent API →

Domande frequenti

Quanto costa la Search API di Perplexity?

5,00 dollari ogni mille richieste riuscite, 1,00 con search_type fast. Una richiesta con fino a cinque query conta come una unità di fatturazione, ma ogni query conta nel limite di frequenza.

Che limite di frequenza ha la Search API?

50 unità al secondo con raffica di 50, uguale per tutti i livelli di utilizzo. Una query vale una unità: una richiesta con cinque query ne consuma cinque.

La Search API genera una risposta?

No. Restituisce risultati con titolo, URL, testo estratto e date. La risposta la costruisce il tuo modello; per questo puoi controllare le fonti e verificare in codice che le citazioni esistano.

Posso restringere la ricerca a certi siti?

Sì, con search_domain_filter: fino a 20 domini o percorsi, in modalità lista consentita oppure lista negata (prefisso trattino), ma non entrambe nella stessa richiesta.

Più avanti nella serie trovi anche l'articolo 5 sul server MCP in Claude Code e Cursor, l'articolo 6 su costi, QPS e 429, l'articolo 7 su PerplexityBot e robots.txt e l'articolo 8 su che cosa è provato per farsi citare.

Fonti

Commenti

Caricamento commenti...

Accedi per commentare

Articoli e strumenti nuovi anche su Telegram

Il canale Telegram segnala gli articoli e gli strumenti nuovi del sito.

Ti è piaciuto questo articolo?

Esplora altri contenuti sul blog o scopri i miei progetti