Kontingente und Ratenlimits

Zwei voneinander unabhängige Dinge begrenzen, was Sie tun können: wie viele Suchen Ihr Tarif pro Tag erlaubt und wie schnell Anfragen eintreffen dürfen. Beides wird in jeder Antwort gemeldet, sodass ein Client sein Tempo selbst steuern kann, ohne erst einen Fehler provozieren zu müssen, um die Grenzen herauszufinden.

Ratenlimit: zehn Anfragen pro Minute

Das Limit gilt pro Konto und wird von der API und dem MCP-Server geteilt: zehn Aufrufe pro Minute, egal auf welchem Weg sie eintreffen. Eine elfte Anfrage innerhalb des Zeitfensters kommt sofort mit 429 too_many_requests zurück und mit einem Retry-After-Header, der die Sekunden bis zum nächsten freien Platz angibt. Derselbe Wert steht im Body als error.retry_after.

HTTP/2 429
Retry-After: 18

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

Warten Sie Retry-After Sekunden und wiederholen Sie die Anfrage. Es wurde nichts verbraucht und kein Kontingent belastet.

Die API hält nie eine Verbindung offen, um Sie auszubremsen. Die alten Export-URLs tun das - sie warten jeweils eine Sekunde, bis zu einer halben Minute, bevor sie ablehnen -, und das ist einer der Gründe, warum es die API gibt.

Tageskontingent

Ihr Tarif erlaubt eine bestimmte Anzahl von Suchanfragen pro Tag und eine bestimmte Anzahl von Schnipsel-Anfragen pro Tag, getrennt gezählt. Beide werden um die nächste Mitternacht UTC zurückgesetzt, nicht 24 Stunden nach der Nutzung.

• Eine Suche verbraucht eine Einheit aus dem Suchkontingent.
• Eine Suche mit snippets=1 verbraucht stattdessen eine Einheit aus dem Schnipsel-Kontingent.
• /v1/account kostet nichts.

Ist ein Kontingent aufgebraucht, wird die Anfrage mit 429 quota_exceeded oder 429 snippet_quota_exceeded abgelehnt - mit Angabe des Limits, des Verbrauchs und der Zeit bis zum Zurücksetzen. Ein aufgebrauchtes Schnipsel-Kontingent stoppt gewöhnliche Suchen nicht.

Ergebnistiefe

Ein Tarif bestimmt außerdem, bis zu welcher Position in der Rangliste Ergebnisse offengelegt werden - disclosed_positions aus /v1/account. Zeilen jenseits dieser Grenze werden weggelassen statt geleert, und wenn das der Fall war, ist truncated im Body true und in den Headern steht X-Truncated: true.

Das ist der wichtigste Unterschied zwischen der API und der Website. Ein Browser, dessen Kontingent aufgebraucht ist, fällt unauffällig auf die Tiefe des kostenlosen Tarifs zurück und zeigt weniger an - für einen Menschen, der eine Seite betrachtet, ist das in Ordnung. Ein Skript bemerkt das nicht, daher lehnt die API ab, statt zu kürzen.

Den aktuellen Stand ablesen

Jede authentifizierte Antwort enthält fünf Header:

Ergebnisse enthalten drei weitere:

Nutzungsstatistik

/v1/account liefert das vollständige Bild mit einem Aufruf und verbraucht nichts:

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

Das ältere https://publicwww.com/profile/api_status.xml?key=... meldet dieselben Zähler als XML und funktioniert weiterhin. Es gehört zu den alten URLs; neuer Code sollte /v1/account verwenden, das auch die Limits meldet, nicht nur die Zähler.