---
title: "Company Search API Reference | Leadsets Docs"
description: "POST /v1/companies/search: filter companies by industry, headcount, country and technology. Match reasons, freshness and 1 search record per result."
canonical: https://www.leadsets.ai/docs/api/companies-search
updated: 2026-11-11
---

REST API / Companies

# Search companies

Find companies by industry, headcount, country and technology. Each record says why it matched and carries a last-seen date and confidence for every field.

POST /v1/companies/search MCP: search_companies

Records

1 per record returned

Meters

records + requests / 5 hrs, records / week

Empty result

0 records · 1 request

## Body parameters

industry string[]

Leadsets industry slugs, e.g. "saas" or "health-care".

employees string

Headcount range: "50-200", "1000+" or "<50".

country string[]

ISO 3166-1 alpha-2, e.g. "US". "UK" is read as "GB".

technology string[]

Technologies the company uses, e.g. "hubspot". Matches any of them.

domain string[]

Only these companies, up to 100 domains. URLs work too.

max_age_days integer

Only records refreshed within this many days, 1–3650.

exclude_stale boolean

Leave out records that are due for a refresh.

limit integer

1–100. Default 25. Free plan: at most 10 per call.

cursor string

From `next_cursor` of the previous page. See [Pagination](https://www.leadsets.ai/docs/pagination).

prompt string

Optional. The request in plain language, up to 1,000 characters. Stored with the call in your request log.

Strings work wherever a list is shown: `"country": "US"` is the same as `"country": ["US"]`.

## Response

`items` (max `limit`), each with `company_id`, `name`, `domain`, `linkedin_url`, `industry`, `naics`, `employees`, `employee_range`, `revenue_range`, `location`, `founded_year`, `description`, `technologies`, `match_reasons`, freshness (`refreshed_at`, `confirmed_at`, `stale_after_at`, `stale`) and `sources`, which gives the last-seen date and confidence of every returned field. Then `next_cursor` for the next page, `usage` with what this call counted and what's left, and `request_id`.

`match_reasons` lists the filters the record matched: `industry`, `size`, `country`, `technology`, `domain`, `fresh`. On the Free plan, `usage` has `free_search_records_left` and `free_calls_left`.

**Searches share one pool.** Company and people searches count against the same concurrent-search limit for your plan. Enrichment and scraping don't take a slot.

## Errors

| Status | type | Meaning |
| --- | --- | --- |
| `400` | `invalid_request` | A value isn't valid. The message names the field in `param`. |
| `401` | `unauthorized` | Missing, invalid, expired or revoked key. See [Authentication](https://www.leadsets.ai/docs/authentication). |
| `402` | `free_records_exhausted` | Free plan: the 100 free search records or the 1,000 free data calls are used up. |
| `403` | `forbidden` | The key is read only. Data tools need a key with data access. |
| `429` | `window_full` | A five-hour records or requests window is full. See Retry-After and `resets_at`. |
| `429` | `weekly_limit` | The seven-day records limit is reached. Resume after `resets_at`. |
| `429` | `too_many_concurrent` | Too many searches running at once for your plan. |

[Previous
**← search_people**](https://www.leadsets.ai/docs/api/people-search) [Next
**enrich_person →**](https://www.leadsets.ai/docs/api/people-enrich)

Was this page useful? [Tell us](mailto:support@leadsets.ai?subject=Docs%20feedback%3A%20%2Fdocs%2Fapi%2Fcompanies-search)

```bash
curl https://api.leadsets.ai/v1/companies/search \
 -H "Authorization: Bearer $LEADSETS_KEY" \
 -H "Content-Type: application/json" \
 -H "Idempotency-Key: 4b0d…" \
 -d '{
   "industry": ["saas"],
   "country": ["US"],
   "employees": "50-200",
   "technology": ["hubspot"],
   "limit": 25
 }'
```

```ts
import { Leadsets } from "@leadsetsai/sdk";

const ls = new Leadsets(process.env.LEADSETS_KEY);
const res = await ls.companies.search({
 industry: ["saas"],
 country: ["US"],
 employees: "50-200",
 technology: ["hubspot"],
 limit: 25,
});
```

```python
import os
from leadsets import Leadsets

ls = Leadsets(os.environ["LEADSETS_KEY"])
res = ls.companies.search(
   industry=["saas"],
   country=["US"],
   employees="50-200",
   technology=["hubspot"],
   limit=25,
)
```

Response 200 OK

```
{
 "items": [{
   "company_id": "8c1f0b7a-52d4-4c3e-9e61-2a7d5f0c9b48",
   "name": "Northwind Analytics",
   "domain": "northwind.io",
   "linkedin_url": "https://www.linkedin.com/company/northwind-analytics",
   "industry": "SaaS",
   "employees": 120, "employee_range": "51-200",
   "location": { "country": "US", "region": "CA", "city": "San Francisco" },
   "founded_year": 2017,
   "technologies": ["hubspot", "segment"],
   "match_reasons": ["industry", "size", "country", "technology"],
   "refreshed_at": "2026-11-01T00:00:00Z", "stale": false
 }],
 "next_cursor": "c_eyJ0Ijoi…",
 "usage": { "search_records_counted": 25, "search_records_left_5h": 7475,
            "search_requests_left_5h": 37499, "search_records_left_week": 37475 },
 "request_id": "req_3f9a1c0b2d4e"
}
```

---

Leadsets by Mobylogix LLC, 10160 hwy 242, Conroe, TX, 77385, US. Facts for AI assistants: https://www.leadsets.ai/llm · Site index: https://www.leadsets.ai/llms.txt · Every page: https://www.leadsets.ai/llms-full.txt