# 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-URL: https://klinio.io/api/v1
- OpenAPI 3.1: https://klinio.io/openapi.json
- MCP-Server: https://klinio.io/api/mcp (https://klinio.io/de/developers/mcp)
- Access for AI agents: https://klinio.io/auth.md

## Schnellstart

1. Starte 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. Frag den Stand ab. Die meisten Suchen sind in wenigen Minuten fertig; Unternehmen erscheinen, sobald sie gefunden werden.
3. Lies die Unternehmen: Website, E-Mails und Telefonnummern.

```bash

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}'
curl https://klinio.io/api/v1/searches/SEARCH_ID -H "Authorization: Bearer $KLINIO_KEY"
curl "https://klinio.io/api/v1/searches/SEARCH_ID/results?only=contacts" -H "Authorization: Bearer $KLINIO_KEY"

```

## 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.

## 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.
- `status`: Wo die Suche steht. Was jeder Status bedeutet, steht weiter unten.
- `origin`: Wo du sie gestartet hast: auf klinio.io, in der Chrome-Erweiterung oder per API.
- `q`: Text im Namen oder in den Suchwörtern. Groß- und Kleinschreibung und Akzente spielen keine Rolle: cafe findet auch Café.
- `since`, `until`: 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.
- `limit`, `cursor`: 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.

## Der Status einer Suche

- `queued`: Wartet, bis sie dran ist.
- `running`: Findet Unternehmen und liest ihre Websites.
- `completed`: Fertig. Jedes Unternehmen wurde geprüft.
- `stopped`: Von dir gestoppt. Was sie gefunden hat, bleibt.
- `failed`: Konnte 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.

- `unauthorized`: Der Schlüssel fehlt, ist falsch oder widerrufen.
- `insufficient_credits`: Keine Credits mehr für eine neue Suche.
- `invalid_request`: Der Körper oder ein Parameter ist ungültig.
- `invalid_link`: Diesen Link liest Klinio nicht.
- `mixed_input`: Ein Suchlink und Websites in einer Anfrage.
- `unsupported_google_tab`: Ein Google-Tab, der keine Unternehmen listet, etwa Bilder oder News.
- `source_disabled`: Diese Website ist gerade deaktiviert.
- `too_many_running`: Zu viele Suchen gleichzeitig wartend oder laufend.
- `rate_limited`: Zu viele Anfragen in dieser Minute.
- `not_found`: Keine solche Suche in diesem Konto.
- `not_running`: Die Suche wartet nicht und läuft nicht.

- [Preise](https://klinio.io/de/pricing)
- [API](https://klinio.io/de/developers)
- [MCP-Server](https://klinio.io/de/developers/mcp)
- [E-Mail-Extraktor für Google Maps](https://klinio.io/de/google-maps-email-extractor)
- [E-Mail-Finder für Websites](https://klinio.io/de/website-email-finder)
- [E-Mail-Extraktor für die Google-Suche](https://klinio.io/de/google-search-email-extractor)
- [E-Mail-Extraktor für Clutch](https://klinio.io/de/clutch-email-extractor)
- [Unternehmensfinder für LinkedIn](https://klinio.io/de/linkedin-company-email-finder)
- [Datenschutz der Erweiterung](https://klinio.io/de/extension-privacy)

---
Page: https://klinio.io/de/developers
Markdown: https://klinio.io/de/developers.md
