# Klinio, from your own code.

Start the same searches as on the site, list your history and read the companies as JSON. The API spends your account's credits, the free daily ones included.

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

## Quick start

1. Start a search with what and where (query and location), or with any link Klinio reads: a Google or Google Maps search, a Clutch directory, or company websites.
2. Check on it. Most searches finish within a few minutes; companies appear as they are found.
3. Read the companies: website, emails and phones.

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

```

## Endpoints

Send your key in the Authorization header as Bearer kl_live_…, and JSON in request bodies. Every answer is JSON.

- `POST /searches`: Start a search. Send query and location (what and where: a Google Maps search), or link (a search link, or websites), or websites (a list). Optionally limit (1 to 500 companies) and country (two letters, for a google.com search link).
- `GET /searches`: Your history: every search started on the site, in the extension or with the API, newest first. Filter it with source, status, origin, q, since and until.
- `GET /searches/{id}`: One search: its status and how many companies it has found.
- `GET /searches/{id}/results`: The companies it found, 100 at a time (limit up to 500). only=contacts keeps those with an email or phone; next_cursor brings the next page.
- `DELETE /searches/{id}`: Stop a queued or running search. What it found stays.
- `GET /account`: Your plan and the credits you have left.

## Your history is in the API too.

Every search you start on the site, in the Chrome extension or with the API goes into one history. List it, filter it, and read any search’s companies at its results_url.

- `source`: Where the search ran. linkedin_list is a LinkedIn list sent from the extension, websites a list of websites, merged lists you joined on the site.
- `status`: Where the search stands. Each status is explained below.
- `origin`: Where you started it: on klinio.io, in the Chrome extension or with the API.
- `q`: Text in the search’s name or words. Capitals and accents don’t matter: cafe also finds Café.
- `since`, `until`: By when the search started: since from that moment, until up to it. Send a date (2026-11-01) or an ISO 8601 time; a date in until includes that whole day.
- `limit`, `cursor`: 1 to 100 searches a page (20 if you don’t say). Send next_cursor back as cursor for the next page; total counts every search that matches.

## A search's status

- `queued`: Waiting for its turn.
- `running`: Finding companies and reading their sites.
- `completed`: Done. Every company has been checked.
- `stopped`: Stopped by you. What it found stays.
- `failed`: Could not finish. failure says why.

## Credits and limits

- One credit is one company with an email or phone, as on the site. Companies with nothing found cost nothing.
- A free account spends its daily credits; a pack spends its balance. With no credits left, a new search answers 402.
- Up to 3 searches queued or running at once per account, and 120 requests a minute per key.
- Browsers can't call the API: it sends no CORS headers, so a key stays on your server.

## Errors

An error answers with its HTTP status and a JSON body: error.code and error.message.

- `unauthorized`: The key is missing, wrong or revoked.
- `insufficient_credits`: No credits left for a new search.
- `invalid_request`: The body or a parameter isn't valid.
- `invalid_link`: Klinio doesn't read that link.
- `mixed_input`: A search link and websites in one request.
- `unsupported_google_tab`: A Google tab that lists no companies, like Images or News.
- `source_disabled`: That site is switched off for now.
- `too_many_running`: Too many searches queued or running at once.
- `rate_limited`: Too many requests this minute.
- `not_found`: No such search on this account.
- `not_running`: The search isn't queued or running.

- [Pricing](https://klinio.io/pricing)
- [API](https://klinio.io/developers)
- [MCP server](https://klinio.io/developers/mcp)
- [Google Maps email extractor](https://klinio.io/google-maps-email-extractor)
- [Website email finder](https://klinio.io/website-email-finder)
- [Google search email extractor](https://klinio.io/google-search-email-extractor)
- [Clutch email extractor](https://klinio.io/clutch-email-extractor)
- [LinkedIn company finder](https://klinio.io/linkedin-company-email-finder)
- [Extension privacy](https://klinio.io/extension-privacy)

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