curl --request POST \
  --url https://api.tryhuntr.com/company-search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "semantic_query": "Companies helping hospitals reduce nurse burnout through workflow automation",
  "filters": {
    "location": {
      "include": [
        "US"
      ]
    },
    "headcount": {
      ">=": 50,
      "<=": 500
    }
  },
  "pagination": {
    "size": 10
  }
}
'

{
  "success": true,
  "request_id": "req_1746123456_cs1x2y",
  "companies": [
    {
      "name": "Stripe",
      "linkedin_slug": "stripe",
      "linkedin_url": "https://www.linkedin.com/company/stripe/",
      "website": "https://stripe.com",
      "description": "Financial infrastructure for the internet.",
      "headquarters": "San Francisco, California, United States",
      "employee_count": 8000,
      "industry": "Software Development",
      "organization_type": "Privately Held",
      "specialities": [
        "Payments",
        "API"
      ]
    }
  ],
  "total": 845,
  "resolved_query": {
    "keyword": {
      "include": [
        "healthcare workflow automation"
      ]
    },
    "location": {
      "include": [
        "US"
      ]
    }
  },
  "pagination": {
    "token": "eyJ...",
    "size": 1
  },
  "price": 0.0003,
  "credits_remaining": 4.9997
}

List building

Search 65M companies with structured filters or natural language

Requires x-api-key header.

Rate limit: 5 requests/second per API key.

Search 65M+ companies in one of two modes: send a structured query, or send a natural-language semantic_query with optional hard filters. Explicit filters override generated fields when both target the same field.

Semantic pagination: The first semantic response includes resolved_query. For page 2 and later, send that object as query together with pagination.token. A semantic request containing a token is rejected so the search cannot be silently regenerated differently.

One page per request: Each call returns at most pagination.size companies (default 100, max 200). Huntr does not auto-fetch additional pages.

Response fields: total = matches for the whole query. companies = rows in this page. resolved_query = generated structured query for semantic requests. pagination = cursor when more pages exist.

Filter logic: include values within a field are OR’d; different fields are AND’d. industry / type must be exact labels.

Use POST /company-search-count with a structured query to preview total for free.

Price: $0.0003 per company returned. Translation failures and empty results are free.

POST

company-search

curl --request POST \
  --url https://api.tryhuntr.com/company-search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "semantic_query": "Companies helping hospitals reduce nurse burnout through workflow automation",
  "filters": {
    "location": {
      "include": [
        "US"
      ]
    },
    "headcount": {
      ">=": 50,
      "<=": 500
    }
  },
  "pagination": {
    "size": 10
  }
}
'

{
  "success": true,
  "request_id": "req_1746123456_cs1x2y",
  "companies": [
    {
      "name": "Stripe",
      "linkedin_slug": "stripe",
      "linkedin_url": "https://www.linkedin.com/company/stripe/",
      "website": "https://stripe.com",
      "description": "Financial infrastructure for the internet.",
      "headquarters": "San Francisco, California, United States",
      "employee_count": 8000,
      "industry": "Software Development",
      "organization_type": "Privately Held",
      "specialities": [
        "Payments",
        "API"
      ]
    }
  ],
  "total": 845,
  "resolved_query": {
    "keyword": {
      "include": [
        "healthcare workflow automation"
      ]
    },
    "location": {
      "include": [
        "US"
      ]
    }
  },
  "pagination": {
    "token": "eyJ...",
    "size": 1
  },
  "price": 0.0003,
  "credits_remaining": 4.9997
}

Authorizations

x-api-key

string

header

required

Your Huntr API key. Get one at tryhuntr.com. Pass as x-api-key header on all authenticated requests.

Body

application/json

Option 1
Option 2

query

object

required

At least one filter required. Combine multiple filters — all must match (AND). See each field for match rules. Invalid industry or type values return HTTP 400 with accepted_values. Use POST /company-search-count to preview total for free.

Show child attributes

semantic_query

string

Natural-language description of the companies to find. Mutually exclusive with query. The response includes resolved_query for deterministic pagination.

Maximum string length: 8000

filters

object

Optional hard constraints used only with semantic_query. Uses the same company filter fields and shapes as query. Explicit fields override generated fields.

pagination

object

One page per request (no auto-fetch). size: companies/people returned this call (default 100, max 200). token: copy from the previous response pagination.token to get the next page — keep the same query. Tokens expire; do not change the query between pages.

Show child attributes

Response

Company search results.

success

boolean

request_id

string

companies

object[]

Matching companies.

Show child attributes

total

integer

Total companies matching the query in the database (not the length of companies).

resolved_query

object

Final structured query generated for a semantic request, including explicit filters. Send this as query with the pagination token for later pages.

pagination

object

Upstream pagination cursor when more pages exist. Pass pagination.token back on the next request with the same query.

Show child attributes

price

number

Cost in USD. $0.0003 × number of companies returned.

credits_remaining

number

Poll research status Count companies matching a query — free

⌘I