Quote e limiti di frequenza

Due cose distinte limitano ciò che puoi fare: quante ricerche al giorno consente il tuo piano e con quale frequenza possono arrivare le richieste. Entrambe sono riportate in ogni risposta, così un client può regolare il proprio ritmo senza dover provocare un errore per scoprire dove sono i limiti.

Limite di frequenza: dieci richieste al minuto

Il limite è per account ed è condiviso tra l'API e il server MCP: dieci chiamate al minuto, da qualunque parte arrivino. Un'undicesima richiesta nella stessa finestra torna immediatamente con 429 too_many_requests e un header Retry-After che indica i secondi mancanti alla liberazione di uno slot. Lo stesso numero è nel corpo come error.retry_after.

HTTP/2 429
Retry-After: 18

{ "error": { "code": "too_many_requests",
             "message": "At most 10 requests per minute.",
             "retry_after": 18 } }

Attendi Retry-After secondi e ripeti la richiesta. Non è stato consumato nulla e non è stata spesa alcuna quota.

L'API non tiene mai aperta una connessione per rallentarti. I vecchi URL di esportazione invece sì: attendono un secondo alla volta per un massimo di mezzo minuto prima di rifiutare, ed è uno dei motivi per cui esiste l'API.

Quota giornaliera

Il tuo piano consente un certo numero di ricerche al giorno e un certo numero di richieste con snippet al giorno, conteggiate separatamente. Entrambe si azzerano alla mezzanotte UTC successiva, non 24 ore dopo l'uso.

Una ricerca costa una unità della quota di ricerche.
Una ricerca con snippets=1 costa invece una unità della quota di snippet.
/v1/account non costa nulla.

Quando una quota è esaurita la richiesta viene rifiutata con 429 quota_exceeded o 429 snippet_quota_exceeded, indicando il limite, quanto è stato usato e quanto manca all'azzeramento. Esaurire la quota degli snippet non blocca le ricerche ordinarie.

Profondità dei risultati

Un piano decide anche fino a che punto della classifica i risultati restano visibili: disclosed_positions di /v1/account. Le righe oltre quel punto vengono omesse anziché svuotate, e quando ne è stata omessa qualcuna truncated è true nel corpo e X-Truncated: true negli header.

È questa la differenza più importante tra l'API e il sito web. Un browser che ha esaurito la quota torna silenziosamente alla profondità del piano gratuito e mostra meno risultati, il che va bene per una persona che guarda una pagina. Uno script non può accorgersene, quindi l'API rifiuta invece di accorciare.

Leggere lo stato attuale

Ogni risposta autenticata contiene cinque header:

Header	Significato
`X-RateLimit-Limit`	Ricerche consentite oggi.
`X-RateLimit-Remaining`	Ricerche rimaste oggi.
`X-RateLimit-Reset`	Ora Unix in cui si azzera la quota del giorno.
`X-Snippets-Limit`	Richieste con snippet consentite oggi.
`X-Snippets-Remaining`	Richieste con snippet rimaste oggi.

I risultati ne contengono altri tre:

Header	Significato
`X-Total-Results`	Quanti siti corrispondono nell'intero indice.
`X-Returned-Results`	Quante righe contiene questa risposta.
`X-Truncated`	`true` quando il limite di profondità del piano ha tolto delle righe.

Statistiche di utilizzo

/v1/account offre il quadro completo in una sola chiamata, e non consuma nulla:

curl -H "Authorization: Bearer $KEY" https://api.publicwww.com/v1/account

{
  "plan": "enterprise",
  "plan_until": 1819461840,
  "full_access": true,
  "quota": {
    "searches": { "limit": 300, "used": 12, "resets_at": 1787961600 },
    "snippets": { "limit": 100, "used": 3,  "resets_at": 1787961600 }
  },
  "limits": {
    "disclosed_positions": 4294967295,
    "disclosed_positions_snippets": 4294967295,
    "max_per_page": 1000000,
    "max_per_page_snippets": 10000
  }
}

Il vecchio https://publicwww.com/profile/api_status.xml?key=... riporta gli stessi contatori in XML e funziona ancora. Fa parte dei vecchi URL; il codice nuovo dovrebbe usare /v1/account, che riporta anche i limiti, non solo i conteggi.

Successivo Errori