Zum Inhalt springen
kosto kosto API v1
OpenAPI Zurück zum Panel

Kosto API · v1

Kosto-API-Dokumentation:
Domain-Autorität in deinen eigenen Tools.

Frage den Authority-Score, den du im Panel siehst, die verweisenden Domains, den direkten Vergleich und die Spam-Prüfung per HTTP ab. Jede Antwort ist JSON, Feldnamen werden in snake_case geschrieben, und zu jedem Endpunkt unten gibt es ein funktionierendes Beispiel.

Basis-URL
Endpunkt
7
Limit pro Minute
120
Format
JSON
Authentifizierung
API-Schlüssel

Authority-Score

Ein Wert von 0–100, Rankings und die Komponenten, aus denen der Wert besteht. Eine Domain oder zehn nebeneinander.

Verweisende Domains

Domains, die auf eine Domain verlinken, nach Wert sortiert; den Mindestwert legst du selbst fest.

Spam-Prüfung

Risikowert und Begründungen für Spam-Signale wie Glücksspiel, Erwachseneninhalte, Pharma oder Replica-Ware.

  • Alle Endpunkte liegen unter /api/v1. Die Version ist Teil der Adresse.
  • Anfragen und Antworten sind UTF-8-JSON. Datumsangaben werden im Format ISO 8601 (UTC) geschrieben.
  • Maschinenlesbare Definition: OpenAPI-3.1-Dokument herunterladen.

Erste Schritte

Schnellstart

Drei Schritte vom Schlüssel bis zur ersten Antwort.

  1. 1

    Schlüssel anfordern

    Erstelle unten einen Schlüssel. Er wird nur im Moment der Erstellung angezeigt; kopiere ihn und speichere ihn an einem sicheren Ort.

  2. 2

    Erste Anfrage senden

    Sende den Schlüssel im Header Authorization. Das Beispiel rechts liegt in der gewählten Sprache bereit; ersetze YOUR_API_KEY durch deinen eigenen Schlüssel.

  3. 3

    Antwort auswerten

    Das Feld authority_score ist der Score von 0 bis 100. Ist found auf false gesetzt, steht die Domain nicht im Link-Index; das ist kein Fehler, es wird 200 zurückgegeben. score_source gibt die Art des Scores an: data ist datenbasiert, standard und calibrated sind Näherungswerte.

Im Panel Ausprobieren unter jedem Endpunkt kannst du die Anfrage direkt aus deinem Browser senden. Der Schlüssel wird nur im Speicher dieses Tabs gehalten, nirgends gespeichert, und es wird keine Anfrage gesendet, bevor du auf die Schaltfläche klickst.

Erste Schritte

Authentifizierung

Jeder Endpunkt außer /api/v1/openapi.json erfordert einen API-Schlüssel. Ein Schlüssel beginnt mit op_ und ist insgesamt 35 Zeichen lang. Verwende einen der beiden folgenden Header; beide erfüllen denselben Zweck.

HTTP-HeaderFormat
AuthorizationBearer op_… (bei Bearer spielt die Groß- und Kleinschreibung keine Rolle)
X-API-Keyop_…

Schlüssel schützen

  • Der Server speichert nicht den Schlüssel selbst, sondern seinen SHA-256-Hash. Wenn du ihn verlierst, erstelle einen neuen Schlüssel und widerrufe den alten.
  • Bewahre den Schlüssel in einer Umgebungsvariable oder in deinem Secrets-Tresor auf. Füge ihn nicht in Quellcode, öffentliche Repositories oder Code ein, der im Browser läuft.
  • Ein widerrufener Schlüssel erhält 403 key_revoked. Fehlt der Schlüssel oder hat er ein falsches Format, wird 401 zurückgegeben.
  • Es wird kein CORS-Header gesendet, daher kann Browsercode einer anderen Website diese API nicht lesen (cross_site_forbidden). Skripte, die Kommandozeile und serverseitiger Code funktionieren problemlos.
  • Im Kontomodus gehört ein Schlüssel zu einem Konto und wird auf den Plan dieses Kontos angerechnet; ein Schlüssel, dessen Konto gesperrt ist oder der keinem Konto zugeordnet ist, erhält 403.

Erste Schritte

Ratenlimits und Kontingente

Es gibt zwei getrennte Limits: Die Ratenbegrenzung pro Minute ist für alle Schlüssel gleich, während die monatlichen und täglichen Kontingente von deinem Plan abhängen.

Ratenlimit: 120 Anfragen pro Minute

Jeder Schlüssel kann in einem festen 60-Sekunden-Fenster 120 Anfragen stellen. Das Fenster öffnet sich mit der ersten Anfrage des Schlüssels, schließt 60 Sekunden später, und der Zähler wird zurückgesetzt. Anfragen ohne gültigen Schlüssel werden in einem gemeinsamen Fenster pro Client-Adresse gezählt. Auch abgelehnte Anfragen (etwa mit 401 oder 400) werden im Fenster mitgezählt. Jede Antwort unter /api/v1 enthält diese Header:

HTTP-HeaderBedeutung
X-RateLimit-LimitAnzahl der erlaubten Anfragen pro Fenster (120).
X-RateLimit-RemainingAnzahl der verbleibenden Anfragen im aktuellen Fenster.
X-RateLimit-ResetZeitpunkt, zu dem das Fenster schließt, in Unix-Sekunden.
Retry-AfterDie Wartezeit in Sekunden bei Antworten mit 429 und 503.

Wird das Limit überschritten, wird 429 rate_limited zurückgegeben. Warte die in Retry-After angegebene Zeit ab und versuche es erneut; wer ohne Warten erneut anfragt, füllt das Fenster nur weiter.

Plankontingente

Im Kontomodus zieht jeder Aufruf eins vom Zähler für API-Anfragen ab. Eine Massenabfrage verbraucht so viele Zeilen der Massenabfrage, wie sie Zeilen hat, eine Spam-Prüfung verbraucht eine Spam-Prüfung. Ein fehlgeschlagener Aufruf gibt das Verbrauchte zurück. Eine Spam-Prüfung derselben Domain am selben Tag wird nicht erneut gezählt (außer mit fresh=1).

PlanAPI-SchlüsselAPI-Anfragen / MonatMassenabfrage-Zeilen / TagSpam-Prüfungen / Tag

Die täglichen und monatlichen Kontingente werden um Mitternacht bzw. zum Monatsanfang nach türkischer Zeit (UTC+3) erneuert. Ist ein Kontingent aufgebraucht, wird 429 quota_exceeded zurückgegeben; die Meldung nennt, welcher Zähler aufgebraucht ist, deine Nutzung und deinen Plan. Die Preise findest du auf der Planseite.

Erste Schritte

Fehlercodes

Fehler kommen mit einem HTTP-Statuscode und immer mit demselben Body. Der code ist stabil, dein Programm sollte also anhand davon verzweigen. Die message ist eine für Menschen geschriebene Beschreibung und kann sich ändern; standardmäßig ist sie auf Englisch, und mit dem Header Accept-Language oder X-Kosto-Lang kannst du eine andere Sprache wählen.

StatusCodeWann
  • Bei Antworten mit 5xx und 429 warte die im Header Retry-After angegebene Zeit ab, sofern er vorhanden ist. Wiederhole eine 4xx-Antwort nicht mit derselben Anfrage; korrigiere stattdessen die Anfrage.
  • Bei einer 405-Antwort nennt der Header Allow die vom Endpunkt unterstützte Methode. HEAD wird wie GET behandelt.
  • Während der Link-Index geladen wird, können Abfragen zu verweisenden Domains 503 graph_unavailable zurückgeben; versuche es nach Retry-After: 15 erneut.

Erste Schritte

Paginierung und Massenanfragen

Die API verwendet weder Cursor (cursor) noch Seitennummern. Endpunkte, die Listen zurückgeben, antworten mit einer einzigen Antwort, deren Größe durch Parameter begrenzt wird.

EndpunktRegel
GET /backlinkslimit beträgt höchstens 1.000 (Standard 100). Der Server wählt zuerst die besten verweisenden Domains nach Score aus, und der Filter min_score wird auf die 1.000 besten verweisenden Domains nach Link-Rang angewendet. Deshalb kann returned mit Filter kleiner als limit ausfallen. total ist die Gesamtzahl der verweisenden Domains, unabhängig vom Filter.
GET /compare2 bis 10 Domains. Schreibweisen, die auf dieselbe Website zeigen, werden zu einer Zeile zusammengeführt; nach der Bereinigung müssen mindestens zwei verschiedene Websites übrig bleiben.
POST /bulkHöchstens 1.000 Domains pro Anfrage, der Body darf höchstens 1 MB groß sein. Bei Überschreitung erhältst du too_many_domains (400) oder payload_too_large (413). Leere Zeilen werden übersprungen, dieselbe Website wird zu einer Zeile zusammengefasst, und ungültige Einträge bleiben als valid: false an ihrer Stelle; die Reihenfolge ist die des ersten Auftretens.

Große Listen aufteilen

Wenn du mehr als 1.000 Domains hast, teile die Liste in Blöcke zu je 1.000 und sende sie nacheinander. Jeder Block ist eine Anfrage und zählt auf das Limit pro Minute; im Kontomodus verbraucht er außerdem so viel Massenabfrage-Kontingent, wie er Zeilen hat.

Sonstiges

Versionierung und Änderungsprotokoll

Die Version ist Teil der Adresse: /api/v1. Das Feld info.version des OpenAPI-Dokuments gibt die Dokumentversion dieser API-Version an.

  • Neue Endpunkte und neue Felder in Antworten können ohne Versionswechsel hinzugefügt werden. Wir erwarten, dass dein Client Felder ignoriert, die er nicht kennt.
  • Inkompatible Änderungen, etwa wenn der Typ oder die Bedeutung eines bestehenden Felds geändert oder ein Feld entfernt wird, erscheinen mit einer neuen Version (/api/v2).
  • Die Texte von message können sich ändern. Verlasse dich auf die Werte von code und die HTTP-Statuscodes.
  1. 1.0.0Aktuelle Version

    Erste Version. Sieben Endpunkte: domain, backlinks, compare, bulk, spam, usage und openapi.json.

    • Schlüsselauthentifizierung: Authorization: Bearer oder X-API-Key.
    • Ratenbegrenzung von 120 Anfragen pro Minute und die Header X-RateLimit-*.
    • Fehlerformat: { "error": { "code", "message" } }.

Sonstiges

Häufige Fragen

Domain nicht gefunden, ist das ein Fehler?

Nein. Für eine Domain, die nicht im Link-Index steht, wird 200 mit found: false zurückgegeben. In diesem Fall sind subdomains und referring_domains null. Eine ungültige Eingabe (Text, der keine Domain ist) liefert dagegen 400 invalid_domain.

Kann ich eine URL senden?

Ja. Der Parameter domain akzeptiert eine Domain oder eine URL. Aus https://www.beispiel.de/seite wird in der Antwort beispiel.de. Dasselbe gilt für bulk und compare.

Warum ist die Anzahl der verweisenden Domains manchmal null?

referring_domains ist null, wenn die Domain nicht im Link-Graphen steht oder der Graph in diesem Moment nicht antworten kann. backlinks gibt 503 graph_unavailable zurück, solange der Graph nicht bereit ist.

Ist der Wert ein Näherungswert oder datenbasiert? Das

Sieh dir das Feld score_source an. Ist es data, wurde der Score aus gemessenen Link- und Traffic-Daten berechnet; das Panel zeigt ihn mit dem Badge datenbasiert und einem ausgefüllten Punkt an. standard und calibrated sind Näherungswerte; das Panel versieht sie mit dem Badge ungefähr und einem leeren Punkt. Sind score_low und score_high vorhanden, geben sie den erwarteten Bereich des Scores an, und das Panel zeichnet diesen Bereich als Bogen auf dem Zifferblatt. Sind beide null, wird kein Bereich gemeldet; das bedeutet nicht, dass der Bereich die Breite null hat.

Warum kann die Anzahl verweisender Domains im Panel von der in der API abweichen?

referring_domains ist immer die Anzahl der im Link-Index gezählten verweisenden Domains, und der Endpunkt backlinks listet diese Domains namentlich auf. Das Panel zeigt in der Überschrift eine einzige Zahl: die Anzahl aus den Suchdaten, wenn Suchdaten für die Domain freigeschaltet wurden, andernfalls die Anzahl aus dem Link-Index. Steht die Anzahl aus den Suchdaten in der Überschrift, erscheint die Anzahl aus dem Link-Index in den Details unter der Karte als die Zahl, die wir „namentlich auflisten können“. Die beiden Zahlen werden mit unterschiedlichen Methoden gemessen, und keine widerlegt die andere.

Warum kann die Spam-Prüfung so langsam sein?

Bei der ersten Abfrage werden die Archiv-, Crawl- und Live-Seitendaten der Domain gelesen, was bis zu 25 Sekunden dauern kann. Das Ergebnis wird 24 Stunden zwischengespeichert (cached: true). Stelle das Timeout deines Clients auf mindestens 30 Sekunden ein. fresh=1 überspringt den Cache und prüft erneut.

Kann ich die API direkt aus dem Browser auf meiner eigenen Website aufrufen?

Nein. Die API sendet keinen CORS-Header und lehnt Browser-Anfragen von anderen Websites ab. Deinen Schlüssel in Browser-Code zu legen wäre ohnehin nicht sicher; rufe die API von deinem eigenen Server aus auf. Das Panel „Ausprobieren“ auf dieser Seite ist die Ausnahme, weil es von derselben Adresse läuft.

Ich habe meinen Schlüssel verloren.

Ein Schlüssel lässt sich nicht wiederherstellen; gespeichert wird nur sein Hash. Erstelle einen neuen Schlüssel, aktualisiere dein Skript und widerrufe den alten.

Wie sehe ich mein Limit?

GET /api/v1/usage gibt die Gesamtzahl der Anfragen deines Schlüssels und den Status des aktuellen Minutenfensters zurück. Im Kontomodus zeigen die Header X-Quota-* bei erfolgreichen Antworten das verbleibende Guthaben des zuletzt gezählten Kontingents; Details findest du auf deiner Kontoseite.

In welcher Zeitzone sind die Zeitstempel?

Die Datumsfelder in den Antworten sind in UTC (etwa 2026-11-10T09:40:36.000Z). Die täglichen und monatlichen Kontingente werden nach türkischer Zeit (UTC+3) erneuert.