# Klinio, dal tuo codice.

Avvia le stesse ricerche del sito, consulta la tua cronologia e ricevi le aziende in JSON. L’API usa i crediti del tuo account, compresi quelli giornalieri gratuiti.

- URL di base: https://klinio.io/api/v1
- OpenAPI 3.1: https://klinio.io/openapi.json
- Server MCP: https://klinio.io/api/mcp (https://klinio.io/it/developers/mcp)
- Access for AI agents: https://klinio.io/auth.md

## Avvio rapido

1. Avvia una ricerca con cosa e dove (query e location), oppure con un link che Klinio sa leggere: una ricerca di Google o Google Maps, una directory Clutch o siti aziendali.
2. Controlla a che punto è. Quasi tutte le ricerche finiscono in pochi minuti; le aziende compaiono man mano che vengono trovate.
3. Leggi le aziende: sito web, email e telefoni.

```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"

```

## Endpoint

Invia la chiave nell’intestazione Authorization come Bearer kl_live_… e i corpi delle richieste in JSON. Ogni risposta è JSON.

- `POST /searches`: Avvia una ricerca. Invia query e location (cosa e dove: una ricerca su Google Maps), oppure link (un link di ricerca o dei siti) o websites (un elenco). Facoltativi: limit (da 1 a 500 aziende) e country (due lettere, per un link di ricerca google.com).
- `GET /searches`: La tua cronologia: ogni ricerca avviata sul sito, nell’estensione o con l’API, dalla più recente. Filtrala con source, status, origin, q, since e until.
- `GET /searches/{id}`: Una ricerca: il suo stato e quante aziende ha trovato finora.
- `GET /searches/{id}/results`: Le aziende trovate, 100 alla volta (limit fino a 500). only=contacts tiene quelle con email o telefono; next_cursor porta alla pagina successiva.
- `DELETE /searches/{id}`: Ferma una ricerca in coda o in corso. Ciò che ha trovato resta.
- `GET /account`: Il tuo piano e i crediti rimasti.

## Anche la tua cronologia è nell’API.

Ogni ricerca che avvii sul sito, nell’estensione di Chrome o con l’API finisce nella stessa cronologia. Elencala, filtrala e leggi le aziende di qualsiasi ricerca dal suo results_url.

- `source`: Dove è stata fatta la ricerca. linkedin_list è una lista LinkedIn inviata dall’estensione, websites un elenco di siti web, merged liste che hai unito sul sito.
- `status`: A che punto è la ricerca. Ogni stato è spiegato più sotto.
- `origin`: Dove l’hai avviata: su klinio.io, nell’estensione di Chrome o con l’API.
- `q`: Testo nel nome o nelle parole della ricerca. Maiuscole e accenti non contano: cafe trova anche Café.
- `since`, `until`: In base a quando è iniziata la ricerca: since da quel momento, until fino ad allora. Invia una data (2026-11-01) o un orario ISO 8601; una data in until include l’intera giornata.
- `limit`, `cursor`: Da 1 a 100 ricerche per pagina (20 se non indichi nulla). Per la pagina successiva rimanda next_cursor come cursor; total conta tutte le ricerche che corrispondono.

## Lo stato di una ricerca

- `queued`: Aspetta il suo turno.
- `running`: Trova aziende e legge i loro siti.
- `completed`: Finita. Ogni azienda è stata controllata.
- `stopped`: Fermata da te. Ciò che ha trovato resta.
- `failed`: Non è riuscita a finire. failure dice perché.

## Crediti e limiti

- Un credito è un’azienda con email o telefono, come sul sito. Le aziende senza risultati non costano nulla.
- Un account gratuito usa i crediti giornalieri, un pacchetto il suo saldo. Senza crediti, una nuova ricerca risponde 402.
- Fino a 3 ricerche in coda o in corso alla volta per account e 120 richieste al minuto per chiave.
- I browser non possono chiamare l’API: non invia intestazioni CORS, così la chiave resta sul tuo server.

## Errori

Un errore risponde con il suo stato HTTP e un corpo JSON: error.code ed error.message.

- `unauthorized`: La chiave manca, è sbagliata o revocata.
- `insufficient_credits`: Nessun credito per una nuova ricerca.
- `invalid_request`: Il corpo o un parametro non è valido.
- `invalid_link`: Klinio non legge questo link.
- `mixed_input`: Un link di ricerca e dei siti nella stessa richiesta.
- `unsupported_google_tab`: Una scheda di Google che non elenca aziende, come Immagini o Notizie.
- `source_disabled`: Questo sito per ora è disattivato.
- `too_many_running`: Troppe ricerche in coda o in corso alla volta.
- `rate_limited`: Troppe richieste in questo minuto.
- `not_found`: Nessuna ricerca così su questo account.
- `not_running`: La ricerca non è in coda né in corso.

- [Prezzi](https://klinio.io/it/pricing)
- [API](https://klinio.io/it/developers)
- [Server MCP](https://klinio.io/it/developers/mcp)
- [Estrattore di email da Google Maps](https://klinio.io/it/google-maps-email-extractor)
- [Trova email da un sito web](https://klinio.io/it/website-email-finder)
- [Estrattore di email da Google](https://klinio.io/it/google-search-email-extractor)
- [Estrattore di email da Clutch](https://klinio.io/it/clutch-email-extractor)
- [Trova aziende su LinkedIn](https://klinio.io/it/linkedin-company-email-finder)
- [Privacy dell’estensione](https://klinio.io/it/extension-privacy)

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