API

Klinio, direkt aus deinem Code.

Starte dieselben Suchen wie auf der Website, ruf deinen Verlauf ab und lies die Unternehmen als JSON. Die API nutzt die Credits deines Kontos, auch die kostenlosen täglichen.

Basis-URLhttps://klinio.io/api/v1

Deine API-Schlüssel

Ein Schlüssel handelt als dein Konto. Bewahre ihn auf deinem Server auf, nie in einer Webseite oder App.

  1. 1Starte eine Suche mit Was und Wo (query und location) oder mit einem Link, den Klinio liest: eine Google- oder Google-Maps-Suche, ein Clutch-Verzeichnis oder Unternehmens-Websites.
  2. 2Frag den Stand ab. Die meisten Suchen sind in wenigen Minuten fertig; Unternehmen erscheinen, sobald sie gefunden werden.
  3. 3Lies die Unternehmen: Website, E‑Mails und Telefonnummern.
# 1. Start a search
curl -X POST https://klinio.io/api/v1/searches \
  -H "Authorization: Bearer $KLINIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "web design agencies", "location": "Ankara", "limit": 50}'

# 2. Check on it (status: queued, running, completed)
curl https://klinio.io/api/v1/searches/SEARCH_ID \
  -H "Authorization: Bearer $KLINIO_KEY"

# 3. Read the companies with an email or phone
curl "https://klinio.io/api/v1/searches/SEARCH_ID/results?only=contacts" \
  -H "Authorization: Bearer $KLINIO_KEY"

Dein Verlauf ist auch in der API.

Jede Suche, die du auf der Website, in der Chrome-Erweiterung oder per API startest, landet im selben Verlauf. Ruf ihn ab, filtere ihn und lies die Unternehmen jeder Suche über ihre results_url.

source
Wo die Suche lief. linkedin_list ist eine LinkedIn-Liste aus der Erweiterung, websites eine Liste von Websites, merged sind Listen, die du auf der Website zusammengeführt hast.google_mapsgoogle_searchclutchlinkedinlinkedin_listwebsitesmerged
status
Wo die Suche steht. Was jeder Status bedeutet, steht weiter unten.queuedrunningcompletedstoppedfailed
origin
Wo du sie gestartet hast: auf klinio.io, in der Chrome-Erweiterung oder per API.siteextensionapi
q
Text im Namen oder in den Suchwörtern. Groß- und Kleinschreibung und Akzente spielen keine Rolle: cafe findet auch Café.
sinceuntil
Nach dem Start der Suche: since ab diesem Zeitpunkt, until bis dahin. Schick ein Datum (2026-11-01) oder eine ISO-8601-Zeit; ein Datum in until schließt den ganzen Tag ein.
limitcursor
1 bis 100 Suchen pro Seite (20, wenn du nichts angibst). Für die nächste Seite schick next_cursor als cursor zurück; total zählt alle passenden Suchen.
# Your whole history, newest first: site, extension and API
curl "https://klinio.io/api/v1/searches?limit=100" \
  -H "Authorization: Bearer $KLINIO_KEY"

# Finished Google Maps searches since 1 November
curl -G https://klinio.io/api/v1/searches \
  -d source=google_maps -d status=completed -d since=2026-11-01 \
  -H "Authorization: Bearer $KLINIO_KEY"

# Searches with "agency" in their name
curl -G https://klinio.io/api/v1/searches -d q=agency \
  -H "Authorization: Bearer $KLINIO_KEY"
GET /searches · Antwort
{
  "data": [{
    "id": "8f2d41c7-3b9e-4c55-a1d0-6e7b2c9f0a13",
    "status": "completed",
    "source": "google_search",
    "query": "web design agency ankara",
    "link": "https://www.google.com/search?q=web+design+agency+ankara&gl=tr",
    "limit": 100,
    "origin": "site",
    "created_at": "2026-11-07T10:19:07.805Z",
    "finished_at": "2026-11-07T10:31:42.118Z",
    "companies": { "found": 71, "with_contacts": 65, "checking": 0 },
    "failure": null,
    "results_url": "/api/v1/searches/8f2d41c7-3b9e-4c55-a1d0-6e7b2c9f0a13/results"
  }],
  "total": 61,
  "next_cursor": "WyIyMDI2LTExLTA3IDEwOjE5OjA3Ljgw…"
}

Endpunkte

Sende deinen Schlüssel im Authorization-Header als Bearer kl_live_… und Anfragekörper als JSON. Jede Antwort ist JSON.

  • POST/searches

    Startet eine Suche. Sende query und location (was und wo: eine Google-Maps-Suche) oder link (ein Suchlink oder Websites) oder websites (eine Liste). Optional limit (1 bis 500 Unternehmen) und country (zwei Buchstaben, für einen google.com-Suchlink).

  • GET/searches

    Dein Verlauf: jede Suche, die auf der Website, in der Erweiterung oder per API gestartet wurde, die neueste zuerst. Filtern kannst du mit source, status, origin, q, since und until.

  • GET/searches/{id}

    Eine Suche: ihr Status und wie viele Unternehmen sie bisher gefunden hat.

  • GET/searches/{id}/results

    Die gefundenen Unternehmen, je 100 (limit bis 500). only=contacts behält die mit E‑Mail oder Telefon; next_cursor holt die nächste Seite.

  • DELETE/searches/{id}

    Stoppt eine wartende oder laufende Suche. Was sie gefunden hat, bleibt.

  • GET/account

    Dein Tarif und deine restlichen Credits.

GET /searches/{id} · Antwort
{
  "id": "1c5c9560-8174-4745-88e0-5682394d69cd",
  "status": "running",
  "source": "google_maps",
  "query": "web design agencies in Ankara",
  "link": "https://www.google.com/maps/search/web+design+agencies+in+Ankara/",
  "limit": 50,
  "origin": "api",
  "created_at": "2026-11-07T15:58:23.257Z",
  "finished_at": null,
  "companies": { "found": 18, "with_contacts": 14, "checking": 4 },
  "failure": null,
  "results_url": "/api/v1/searches/1c5c9560-8174-4745-88e0-5682394d69cd/results"
}
GET /searches/{id}/results · Antwort
{
  "search_status": "completed",
  "data": [{
    "id": "b0a3e7c2-5d4f-4a8e-9c61-2f7d8e1a4b90",
    "company": "Bilgeweb Interactive",
    "website": "https://www.bilgeweb.com.tr",
    "emails": ["info@bilgeweb.com.tr"],
    "phones": ["+90 312 911 75 02"],
    "location": "Yenimahalle/Ankara, Türkiye",
    "industry": "Advertising agency",
    "source": "google_maps",
    "status": "done",
    "created_at": "2026-11-07T15:58:31.904Z"
  }],
  "next_cursor": null
}

Der Status einer Suche

  • queuedWartet, bis sie dran ist.
  • runningFindet Unternehmen und liest ihre Websites.
  • completedFertig. Jedes Unternehmen wurde geprüft.
  • stoppedVon dir gestoppt. Was sie gefunden hat, bleibt.
  • failedKonnte nicht fertig werden. failure nennt den Grund.

Credits und Grenzen

  • Ein Credit ist ein Unternehmen mit E‑Mail oder Telefon, wie auf der Website. Unternehmen ohne Treffer kosten nichts.
  • Ein kostenloses Konto nutzt seine täglichen Credits, ein Paket sein Guthaben. Ohne Credits antwortet eine neue Suche mit 402.
  • Bis zu 3 Suchen gleichzeitig wartend oder laufend pro Konto und 120 Anfragen pro Minute und Schlüssel.
  • Browser können die API nicht aufrufen: Sie sendet keine CORS-Header, so bleibt ein Schlüssel auf deinem Server.

Fehler

Ein Fehler antwortet mit seinem HTTP-Status und einem JSON-Körper: error.code und error.message.

  • 400invalid_requestDer Körper oder ein Parameter ist ungültig.
  • 400invalid_linkDiesen Link liest Klinio nicht.
  • 400mixed_inputEin Suchlink und Websites in einer Anfrage.
  • 400unsupported_google_tabEin Google-Tab, der keine Unternehmen listet, etwa Bilder oder News.
  • 401unauthorizedDer Schlüssel fehlt, ist falsch oder widerrufen.
  • 402insufficient_creditsKeine Credits mehr für eine neue Suche.
  • 403source_disabledDiese Website ist gerade deaktiviert.
  • 404not_foundKeine solche Suche in diesem Konto.
  • 409not_runningDie Suche wartet nicht und läuft nicht.
  • 429too_many_runningZu viele Suchen gleichzeitig wartend oder laufend.
  • 429rate_limitedZu viele Anfragen in dieser Minute.