> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airscale.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Company lookalikes
> Find companies similar to your reference domains. Rate limit: 15 requests per rolling minute per workspace. Maximum 5 active searches per workspace.
Find companies similar to one or more reference companies. The request waits for the search to finish and returns company data directly.
Costs **0.5 credits per unique returned company**. Before searching, the API reserves `limit × 0.5` credits and refunds the unused amount afterward. Zero results cost zero credits. Each workspace can start **15 searches per rolling minute** and have **5 active searches** at a time.
Authenticate with your workspace API key. See [Authentication](/api-reference/authentication).
## Reference domains and result limits
Send 1–10 company websites in `domains`. Domains and website URLs are normalized and deduplicated. LinkedIn URLs and IP addresses are not accepted. Reference companies and domains listed in `exclude.domains` are omitted from results.
`limit` defaults to **2,000** and applies to the **entire response**:
| Distinct reference domains | Maximum total results |
| - | - |
| 1 | 2,000 |
| 2 | 4,000 |
| 3–10 | 5,000 |
For example, ten reference domains with `limit: 5000` request at most 5,000 unique companies in total. Results are deduplicated across references and may be fewer than requested. All results are returned in a single response.
## Filters
Use `include` and `exclude` to filter by country, city, and employee size. Country filters accept country names or ISO alpha-2 codes. A location filter that cannot be resolved can return `422`.
Each country or city list accepts up to 100 values. Supported size bands are `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, and `10001+`. Use `exclude.domains` to omit up to 900 company websites.
Use `founded.min` and `founded.max` for founding-year bounds from 1000 through 9999; the minimum cannot exceed the maximum.
## Company fields
The response contains `status`, `total_results`, `credits_used`, `data`, and `warnings`. Every company in `data` includes all of these fields:
| Field | Meaning |
| - | - |
| `domain` | Normalized company domain. |
| `name` | Company name; falls back to the domain when missing. |
| `description` | Company description. |
| `employee_count` | String, commonly an employee range rather than an exact headcount. |
| `country`, `city` | Company location. |
| `founded_year` | Integer founding year, or `null`. |
| `linkedin_url` | LinkedIn company profile URL. |
| `relevance_score` | Number or `null`; not a confidence percentage or guaranteed to be between 0 and 1. |
| `matched_domains` | Normalized reference domains that matched this company. |
Missing text fields are empty strings. Companies matching more reference domains appear first.
Check `warnings` for any reference companies that could not be searched. No matches returns an empty `data` array and costs zero credits.
## Credits
A request with `limit: 10` requires 5 available credits; `limit: 5000` requires 2,500. Insufficient available credits returns `402`. The final charge is based on the unique companies returned, and `credits_used` reports that amount.
Do not automatically retry this request. A search may complete even when you receive an error or no response, and repeating it can cause another charge.
## Timing and errors
Allow at least **100 seconds** for your client timeout. If a search times out, try fewer reference companies or a lower result limit.
A rate or concurrency limit returns `429`. Wait for the number of seconds in `Retry-After` when present. See [Rate limits](/api-reference/rate-limits).
## Next step
Use [Find people](/api-reference/find-people) to search for roles at matching companies, or [Find companies](/api-reference/find-companies) to search using firmographic filters instead of reference domains.
## OpenAPI
````yaml openapi.json POST /v1/company-lookalikes
openapi: 3.1.0
info:
title: Airscale Public API
version: '2026-09-11'
description: Search, enrich, and resolve public business data with Airscale.
x-airscale-source-repository: ViceScale/airscale-code
x-airscale-source-sha: 1de19e1b70a052a4b8d9c2075021a7e5e7a94d51
servers:
- url: https://api.airscale.io
description: Production
security:
- bearerAuth: []
tags:
- name: Search and discovery
description: Search people, companies, and the web.
- name: Contact data
description: Find professional and personal contact data.
- name: Profiles and reverse lookup
description: Extract profiles or resolve a person from known contact data.
- name: Post engagement
description: Retrieve and enrich people who liked or commented on LinkedIn posts.
- name: LinkedIn content
description: >-
Search LinkedIn posts, read profile and company feeds, and retrieve
profile comments and comment reactions.
- name: Account
description: Inspect workspace account state.
- name: Miscellaneous
description: Check WhatsApp availability, Meta ads, and email deliverability.
paths:
/v1/company-lookalikes:
post:
tags:
- Search and discovery
summary: Find company lookalikes
description: >-
Finds companies similar to 1–10 reference domains and returns all
results in a single response. Use your workspace API key and allow at
least 100 seconds for the client timeout. Do not automatically retry
this request. A search may complete even when you receive an error or no
response, and repeating it can cause another charge.
operationId: findCompanyLookalikes
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domains
additionalProperties: false
properties:
domains:
type: array
minItems: 1
maxItems: 10
items:
type: string
minLength: 1
maxLength: 2048
description: >-
Reference company websites, normalized to domains and
deduplicated. Accepts domains or website URLs, not LinkedIn
URLs or IP addresses. Reference companies are excluded from
results.
limit:
type: integer
minimum: 1
maximum: 5000
default: 2000
description: >-
Total unique results across all references, not per domain.
Maximum min(5000, 2000 × distinct normalized reference
domains): 2000 for one, 4000 for two, 5000 for three through
ten. Searches may return fewer results.
include:
type: object
additionalProperties: false
properties:
country:
type: array
maxItems: 100
items:
type: string
minLength: 1
maxLength: 120
description: >-
Country names or ISO alpha-2 codes. Codes are normalized
before searching.
city:
type: array
maxItems: 100
items:
type: string
minLength: 1
maxLength: 120
description: >-
City names. A location filter that cannot be resolved
can return HTTP 422.
size:
type: array
maxItems: 8
items:
type: string
enum:
- 1-10
- 11-50
- 51-200
- 201-500
- 501-1000
- 1001-5000
- 5001-10000
- 10001+
description: Employee size bands.
description: Optional company filters to include.
exclude:
type: object
additionalProperties: false
properties:
country:
type: array
maxItems: 100
items:
type: string
minLength: 1
maxLength: 120
description: >-
Country names or ISO alpha-2 codes. Codes are normalized
before searching.
city:
type: array
maxItems: 100
items:
type: string
minLength: 1
maxLength: 120
description: >-
City names. A location filter that cannot be resolved
can return HTTP 422.
size:
type: array
maxItems: 8
items:
type: string
enum:
- 1-10
- 11-50
- 51-200
- 201-500
- 501-1000
- 1001-5000
- 5001-10000
- 10001+
description: Employee size bands.
domains:
type: array
maxItems: 900
items:
type: string
minLength: 1
maxLength: 2048
description: Company websites to omit, normalized to domains.
description: Optional company filters and domains to exclude.
founded:
type: object
additionalProperties: false
properties:
min:
type: integer
minimum: 1000
maximum: 9999
max:
type: integer
minimum: 1000
maximum: 9999
description: Optional founding-year bounds. min cannot exceed max.
examples:
simple:
summary: Find up to ten similar companies
value:
domains:
- example.com
limit: 10
filtered:
summary: Filter a combined search
value:
domains:
- example.com
- example.org
limit: 100
include:
country:
- France
size:
- 51-200
exclude:
domains:
- excluded.example.com
founded:
min: 2000
max: 2026
responses:
'200':
description: >-
Completed search. Companies are unique by domain. Partial reference
failures can return remaining results with warnings. Empty results
cost zero credits.
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- status
- total_results
- credits_used
- data
- warnings
properties:
status:
type: string
const: success
total_results:
type: integer
minimum: 0
maximum: 5000
description: Number of companies in data.
credits_used:
type: number
minimum: 0
maximum: 2500
description: 'Actual charge: total_results × 0.5 credits.'
data:
type: array
maxItems: 5000
items:
type: object
additionalProperties: false
required:
- domain
- name
- description
- employee_count
- country
- city
- founded_year
- linkedin_url
- relevance_score
- matched_domains
properties:
domain:
type: string
description: Normalized company domain.
name:
type: string
description: Company name; falls back to the domain when missing.
description:
type: string
description: Company description, or an empty string.
employee_count:
type: string
description: >-
Available employee size, commonly a range; not an
exact headcount. Empty string when missing.
country:
type: string
description: Country, or an empty string.
city:
type: string
description: City, or an empty string.
founded_year:
type:
- integer
- 'null'
description: Founding year, or null when missing.
linkedin_url:
type: string
description: LinkedIn company URL, or an empty string.
relevance_score:
type:
- number
- 'null'
description: >-
Available relevance score, or null. Not a confidence
percentage and not guaranteed to be between 0 and 1.
matched_domains:
type: array
minItems: 1
maxItems: 10
items:
type: string
description: >-
Normalized reference domains that matched this
company.
warnings:
type: array
items:
type: string
description: >-
Partial reference failures or omitted invalid websites.
Empty when no warnings occurred.
examples:
success:
summary: Synthetic company match
value:
status: success
total_results: 1
credits_used: 0.5
data:
- domain: match.example.com
name: Example Company
description: Software for sales teams.
employee_count: 51-200
country: France
city: Paris
founded_year: 2018
linkedin_url: https://www.linkedin.com/company/example
relevance_score: 0.87
matched_domains:
- example.com
warnings: []
empty:
summary: No matching companies
value:
status: success
total_results: 0
credits_used: 0
data: []
warnings: []
'400':
description: >-
Invalid JSON, unsupported content type, unknown fields, or invalid
filters or limits.
content:
application/json:
schema:
type: object
required:
- error
- code
additionalProperties: false
properties:
error:
type: string
description: Safe error message.
code:
type: string
description: Stable error code.
'401':
description: Missing, invalid, or revoked workspace API key.
content:
application/json:
schema:
type: object
required:
- error
- code
additionalProperties: false
properties:
error:
type: string
description: Safe error message.
code:
type: string
description: Stable error code.
'402':
description: Not enough available credits to reserve limit × 0.5 credits.
content:
application/json:
schema:
type: object
required:
- error
- code
additionalProperties: false
properties:
error:
type: string
description: Safe error message.
code:
type: string
description: Stable error code.
'404':
description: >-
None of the reference companies could be found
(reference_company_not_found).
content:
application/json:
schema:
type: object
required:
- error
- code
additionalProperties: false
properties:
error:
type: string
description: Safe error message.
code:
type: string
description: Stable error code.
'422':
description: A location filter could not be resolved.
content:
application/json:
schema:
type: object
required:
- error
- code
additionalProperties: false
properties:
error:
type: string
description: Safe error message.
code:
type: string
description: Stable error code.
'429':
description: >-
The workspace has reached 15 starts per rolling minute, already has
5 active searches, or search capacity is temporarily unavailable.
Inspect Retry-After when present.
headers:
Retry-After:
description: Seconds to wait when present. A later POST starts a new search.
schema:
type: integer
minimum: 1
content:
application/json:
schema:
type: object
required:
- error
- code
additionalProperties: false
properties:
error:
type: string
description: Safe error message.
code:
type: string
description: Stable error code.
'502':
description: The search could not be completed.
content:
application/json:
schema:
type: object
required:
- error
- code
additionalProperties: false
properties:
error:
type: string
description: Safe error message.
code:
type: string
description: Stable error code.
'503':
description: Company search is temporarily unavailable.
content:
application/json:
schema:
type: object
required:
- error
- code
additionalProperties: false
properties:
error:
type: string
description: Safe error message.
code:
type: string
description: Stable error code.
'504':
description: The search deadline was exceeded (company_lookalikes_timeout).
content:
application/json:
schema:
type: object
required:
- error
- code
additionalProperties: false
properties:
error:
type: string
description: Safe error message.
code:
type: string
description: Stable error code.
x-codeSamples:
- label: cURL
lang: bash
source: |-
curl --request POST \
--url https://api.airscale.io/v1/company-lookalikes \
--max-time 100 \
--header "Authorization: Bearer $AIRSCALE_API_KEY" \
--header "Content-Type: application/json" \
--data '{"domains":["example.com"],"limit":10}'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API key
description: >-
Use an Airscale workspace API key. Never expose the key in client-side
code.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.