API

O Klinio, direto do seu código.

Inicie as mesmas buscas do site, consulte seu histórico e receba as empresas em JSON. A API usa os créditos da sua conta, incluindo os créditos diários gratuitos.

URL basehttps://klinio.io/api/v1

Suas chaves de API

Uma chave age como a sua conta. Guarde-a no seu servidor, nunca numa página web ou num app.

  1. 1Inicie uma busca com o quê e onde (query e location), ou com um link que o Klinio lê: uma busca do Google ou do Google Maps, um diretório do Clutch ou sites de empresas.
  2. 2Acompanhe. A maioria das buscas termina em poucos minutos; as empresas aparecem à medida que são encontradas.
  3. 3Leia as empresas: site, e‑mails e telefones.
# 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"

Seu histórico também está na API.

Toda busca que você inicia no site, na extensão do Chrome ou pela API vai para o mesmo histórico. Liste, filtre e leia as empresas de qualquer busca pelo results_url dela.

source
Onde a busca foi feita. linkedin_list é uma lista do LinkedIn enviada pela extensão, websites uma lista de sites, merged listas que você juntou no site.google_mapsgoogle_searchclutchlinkedinlinkedin_listwebsitesmerged
status
Em que ponto a busca está. Cada status é explicado mais abaixo.queuedrunningcompletedstoppedfailed
origin
Onde você a iniciou: no klinio.io, na extensão do Chrome ou pela API.siteextensionapi
q
Texto no nome ou nas palavras da busca. Maiúsculas e acentos não importam: cafe também encontra Café.
sinceuntil
Pelo momento em que a busca começou: since a partir dele, until até ele. Envie uma data (2026-11-01) ou um horário ISO 8601; uma data em until inclui o dia inteiro.
limitcursor
De 1 a 100 buscas por página (20 se você não indicar). Para a próxima página, envie next_cursor como cursor; total conta todas as buscas que correspondem.
# 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 · Resposta
{
  "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…"
}

Endpoints

Envie a chave no cabeçalho Authorization como Bearer kl_live_… e os corpos das requisições em JSON. Toda resposta é JSON.

  • POST/searches

    Inicia uma busca. Envie query e location (o quê e onde: uma busca no Google Maps), ou link (um link de busca, ou sites), ou websites (uma lista). Opcionais: limit (de 1 a 500 empresas) e country (duas letras, para um link de busca do google.com).

  • GET/searches

    Seu histórico: todas as buscas iniciadas no site, na extensão ou pela API, da mais recente para a mais antiga. Filtre com source, status, origin, q, since e until.

  • GET/searches/{id}

    Uma busca: o status e quantas empresas encontrou até agora.

  • GET/searches/{id}/results

    As empresas encontradas, 100 por vez (limit até 500). only=contacts mantém as que têm e‑mail ou telefone; next_cursor traz a próxima página.

  • DELETE/searches/{id}

    Para uma busca na fila ou em andamento. O que ela encontrou fica.

  • GET/account

    Seu plano e os créditos que restam.

GET /searches/{id} · Resposta
{
  "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 · Resposta
{
  "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
}

O status de uma busca

  • queuedAguardando a vez.
  • runningEncontrando empresas e lendo os sites delas.
  • completedPronta. Todas as empresas foram verificadas.
  • stoppedParada por você. O que ela encontrou fica.
  • failedNão conseguiu terminar. failure diz o porquê.

Créditos e limites

  • Um crédito é uma empresa com e‑mail ou telefone, como no site. Empresas sem nada encontrado não custam nada.
  • Uma conta gratuita usa os créditos diários; um pacote, o saldo. Sem créditos, uma nova busca responde 402.
  • Até 3 buscas na fila ou em andamento ao mesmo tempo por conta, e 120 requisições por minuto por chave.
  • Navegadores não conseguem chamar a API: ela não envia cabeçalhos CORS, então a chave fica no seu servidor.

Erros

Um erro responde com o status HTTP e um corpo JSON: error.code e error.message.

  • 400invalid_requestO corpo ou um parâmetro não é válido.
  • 400invalid_linkO Klinio não lê esse link.
  • 400mixed_inputUm link de busca e sites na mesma requisição.
  • 400unsupported_google_tabUma aba do Google que não lista empresas, como Imagens ou Notícias.
  • 401unauthorizedA chave está faltando, errada ou revogada.
  • 402insufficient_creditsSem créditos para uma nova busca.
  • 403source_disabledEsse site está desativado no momento.
  • 404not_foundNenhuma busca assim nesta conta.
  • 409not_runningA busca não está na fila nem em andamento.
  • 429too_many_runningBuscas demais na fila ou em andamento ao mesmo tempo.
  • 429rate_limitedRequisições demais neste minuto.