Quotas et limites de débit

Deux choses distinctes encadrent ce que vous pouvez faire : le nombre de recherches que votre forfait autorise par jour, et la vitesse à laquelle les requêtes peuvent arriver. Les deux sont indiqués dans chaque réponse : un client peut ainsi régler son rythme sans avoir à provoquer une erreur pour découvrir où se trouvent les limites.

Limite de débit : dix requêtes par minute

La limite s’applique par compte et est partagée entre l’API et le serveur MCP : dix appels par minute, quelle que soit leur provenance. Une onzième requête dans cette fenêtre reçoit immédiatement la réponse 429 too_many_requests avec un en-tête Retry-After indiquant le nombre de secondes avant qu’un créneau se libère. Le même nombre figure dans le corps, sous error.retry_after.

HTTP/2 429
Retry-After: 18

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

Attendez Retry-After secondes et renvoyez la requête. Rien n’a été consommé et aucun quota n’a été dépensé.

L’API ne maintient jamais une connexion ouverte pour vous ralentir. Les anciennes URL d’export le font - elles patientent une seconde à la fois, jusqu’à une demi-minute, avant de refuser -, et c’est l’une des raisons d’être de l’API.

Quota quotidien

Votre forfait autorise un certain nombre de recherches par jour et un certain nombre de requêtes avec extraits par jour, décomptés séparément. Les deux sont remis à zéro à minuit UTC, et non 24 heures après utilisation.

• Une recherche coûte une unité du quota de recherches.
• Une recherche avec snippets=1 coûte à la place une unité du quota d’extraits.
• /v1/account ne coûte rien.

Lorsqu’un quota est épuisé, la requête est refusée avec 429 quota_exceeded ou 429 snippet_quota_exceeded, en indiquant la limite, ce qui a été utilisé et le délai avant la remise à zéro. Épuiser le quota d’extraits n’empêche pas les recherches ordinaires.

Profondeur des résultats

Un forfait détermine aussi jusqu’où, dans le classement, les résultats restent dévoilés - disclosed_positions dans /v1/account. Les lignes au-delà de ce point sont omises plutôt que vidées et, si c’est le cas, truncated vaut true dans le corps et X-Truncated: true figure dans les en-têtes.

C’est la différence la plus importante entre l’API et le site. Un navigateur dont le quota est épuisé revient discrètement à la profondeur de l’offre gratuite et affiche moins de résultats, ce qui convient à une personne qui regarde une page. Un script ne peut pas s’en apercevoir : l’API refuse donc au lieu de raccourcir.

Lire l’état actuel

Chaque réponse authentifiée comporte cinq en-têtes :

Les résultats en comportent trois de plus :

Statistiques d’utilisation

/v1/account donne une vue complète en un seul appel, sans rien consommer :

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
  }
}

L’ancienne adresse https://publicwww.com/profile/api_status.xml?key=... renvoie les mêmes compteurs en XML et fonctionne toujours. Elle fait partie des anciennes URL ; le nouveau code doit utiliser /v1/account, qui indique aussi les limites, et pas seulement les compteurs.