> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryhuntr.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi.json post /company-search openapi: 3.0.3 info: title: Huntr — The GTM Intelligence API description: >- Give AI agents company, people, contact, and web intelligence through one API. Search accounts, build targeted lists, enrich leads, find contacts, and uncover buying signals. **Authentication:** Authenticated endpoints require an `x-api-key` header with your Huntr API key. Get a key by signing up via `POST /keys/create`. Public endpoints (pricing, sign-up, health) work without a key. **Rate limit:** 5 requests/second per API key on authenticated endpoints. version: 2.0.0 servers: - url: https://api.tryhuntr.com security: [] tags: - name: Research description: >- Research one company, person, team, or focused business question and return a sales-ready answer. Lite, standard, and deep tiers. - name: Companies description: >- Search companies and enrich firmographics. Per-result pricing on search; count endpoints are free. - name: People description: >- Search people and enrich contacts — work email, phone, and related lookup endpoints. - name: LinkedIn description: >- LinkedIn URL discovery, company and profile pages, posts, reactions, and comments. - name: X description: X profiles, posts, search results, and thread context. - name: Web description: >- Find and analyze pages on a domain, plus tech stack, domain contacts, and job postings. - name: Account description: >- Sign up, verify email, recover keys, check balance, view usage, add credits, and read the public pricing matrix. - name: System description: Health check. paths: /company-search: post: tags: - Companies summary: Search 65M companies with structured filters or natural language description: >- **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. requestBody: required: true content: application/json: schema: type: object oneOf: - required: - query - required: - semantic_query properties: semantic_query: type: string maxLength: 8000 description: >- Natural-language description of the companies to find. Mutually exclusive with `query`. The response includes `resolved_query` for deterministic pagination. filters: type: object description: >- Optional hard constraints used only with `semantic_query`. Uses the same company filter fields and shapes as `query`. Explicit fields override generated fields. additionalProperties: true query: type: object description: >- 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. properties: name: type: object description: >- **Company legal/display name.** Open text — substring match (not exact). Use when you do not know the domain. Prefer `domain` when you have stripe.com-style identifiers for exact company matching. Example: `{ "include": ["Stripe", "Bell Security Solutions Inc."] }`. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. lid: type: object description: >- **LinkedIn company vanity ID** — the slug at the end of `linkedin.com/company/{lid}`. Example: `google` from `https://www.linkedin.com/company/google/`. Exact match on that ID. Best for looking up one known company page. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. urn: type: object description: >- **LinkedIn company URN (numeric ID only).** Example: `"1527"`. Do not pass the full `urn:li:fs_salesCompany:…` string — numeric ID only. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. companyId: type: object description: >- **Flexible company identifier.** Accepts any of: website domain (`stripe.com`), numeric URN (`5678`), full LinkedIn company URL, or vanity name (`stripe` from `linkedin.com/company/stripe`). Use when you have a URL or mixed ID formats. Prefer `domain` for bulk domain lists. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. type: type: object description: >- **LinkedIn company type (legal structure).** Must be exact labels. Allowed: `Privately Held`, `Sole Proprietorship`, `Self-Employed`, `Partnership`, `Public Company`, `Nonprofit`, `Educational Institution`, `Government Agency`. This is **not** funding stage — use `keyword` for terms like "Series A" or "seed". Huntr returns 400 with full `accepted_values` if a label is wrong. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. industry: type: object description: >- **LinkedIn industry label (exact match).** Must match LinkedIn's industry taxonomy exactly (e.g. `Software Development`, not `Software` or `SaaS`). Huntr validates on request and returns HTTP 400 with `invalid_values` and the full `accepted_values` list when a label is wrong. Example: `{ "include": ["Software Development"] }`. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. location: type: object description: >- **Company headquarters location.** City, state, or country name works; **alpha-2 country codes** (`US`, `FR`, `GB`) give the best results. Example: `{ "include": ["US"] }`. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. domain: type: object description: >- **Company website domain (exact).** Use bare domains (`stripe.com`), not full URLs (`https://www.stripe.com`). Strongly preferred over `name` when you know the domain — avoids fuzzy name collisions. Do not use `linkedin.com`. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. keyword: type: object description: >- **Full-text search across the company profile** — name, description, specialties, etc. Open text. Use for concepts with no dedicated filter (e.g. "AI startup", "higher education"). Not a substitute for exact `industry` labels. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. headcount: type: object description: >- **Employee count range (integer).** Use comparison operators only: `>`, `<`, `>=`, `<=` — not `min`/`max`. Multiple operators on one object are AND'd. Example: `{ ">": 10, "<": 500 }` matches 11–499 employees. additionalProperties: type: number example: '>': 10 <: 500 headcountGrowth: type: object description: >- **Headcount growth rate (% over a period).** Required shape: `{ "timespan": "6months"|"12months"|"24months", "min": number, "max": number }`. Percent scale: `0` = flat, positive = growth, negative = shrinkage, `-100` = no employees left. `min`/`max` range: -100 to 10000. Huntr validates `timespan` and returns 400 with allowed values if invalid. properties: timespan: type: string enum: - 6months - 12months - 24months description: Measurement window. min: type: number description: Minimum growth % (inclusive). max: type: number description: Maximum growth % (inclusive). example: timespan: 6months min: -10 max: 50 revenue: type: object description: >- **Annual revenue range in USD (integer).** Same operators as `headcount`: `>`, `<`, `>=`, `<=`. Example: `{ ">": 1000000 }` for revenue above $1M. additionalProperties: type: number example: '>': 1000000 pagination: type: object description: >- 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. properties: size: type: integer minimum: 1 maximum: 200 default: 100 description: >- Page size for this request (1–200). You are charged per row returned, up to this size. token: type: string description: >- Opaque cursor from the prior response. Omit on the first page. examples: semantic: summary: Natural-language company discovery with hard filters value: semantic_query: >- Companies helping hospitals reduce nurse burnout through workflow automation filters: location: include: - US headcount: '>=': 50 <=: 500 pagination: size: 10 by_industry: summary: First page — industry, headcount, country value: query: industry: include: - Software Development headcount: '>': 50 location: include: - US pagination: size: 10 by_domain: summary: By domain value: query: domain: include: - stripe.com pagination: size: 1 next_page: summary: Next page (same query) value: query: industry: include: - Software Development headcount: '>': 50 location: include: - US pagination: size: 10 token: eyJ... responses: '200': description: Company search results. content: application/json: schema: type: object properties: success: type: boolean request_id: type: string companies: type: array description: Matching companies. items: type: object properties: name: type: string linkedin_url: type: string description: LinkedIn company page URL. linkedin_slug: type: string description: LinkedIn company vanity slug (e.g. stripe). linkedin_urn: type: string description: Numeric LinkedIn company URN. website: type: string description: type: string headquarters: type: string description: Headquarters address. employee_count: type: integer description: Employee count when known. employee_range: type: string description: >- Declarative headcount range when exact count is unavailable. industry: type: string organization_type: type: string description: Legal structure (e.g. Privately Held). phone: type: string founded: type: string logo: type: string description: Company logo image URL. specialities: type: array items: type: string employee_growth: type: array items: type: object properties: period: type: string percent: type: number revenue: type: object properties: amount: type: number unit: type: string description: BILLION, MILLION, THOUSAND, etc. currency: type: string description: Three-letter currency code. description: Known disclosed revenue when available. estimated_revenue_min: type: object properties: amount: type: number unit: type: string description: BILLION, MILLION, THOUSAND, etc. currency: type: string description: Three-letter currency code. estimated_revenue_max: type: object properties: amount: type: number unit: type: string description: BILLION, MILLION, THOUSAND, etc. currency: type: string description: Three-letter currency code. estimated_revenue_range: description: >- Estimated revenue band — either a single amount or min/max pair. oneOf: - type: object properties: amount: type: number unit: type: string description: BILLION, MILLION, THOUSAND, etc. currency: type: string description: Three-letter currency code. - type: object properties: min: type: object properties: amount: type: number unit: type: string description: BILLION, MILLION, THOUSAND, etc. currency: type: string description: Three-letter currency code. max: type: object properties: amount: type: number unit: type: string description: BILLION, MILLION, THOUSAND, etc. currency: type: string description: Three-letter currency code. total: type: integer description: >- Total companies matching the query in the database (not the length of companies). resolved_query: type: object description: >- Final structured query generated for a semantic request, including explicit filters. Send this as `query` with the pagination token for later pages. additionalProperties: true pagination: type: object description: >- Upstream pagination cursor when more pages exist. Pass pagination.token back on the next request with the same query. properties: token: type: string description: Opaque cursor for the next page. size: type: integer description: >- Upstream page size metadata (usually matches rows returned this page). price: type: number description: Cost in USD. $0.0003 × number of companies returned. credits_remaining: type: number example: 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 '400': description: >- Empty query, unknown filter key, or invalid enum value (`industry`, `type`, `headcountGrowth.timespan`). Response includes `field`, `invalid_values`, and `accepted_values` when applicable. content: application/json: schema: $ref: '#/components/schemas/QueryValidationError' example: error: >- Invalid industry value(s). Use exact labels from accepted_values. field: query.industry invalid_values: - Software accepted_values: - Software Development - Real Estate '401': description: Invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: Insufficient credits. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Search failed. Credits are refunded automatically. content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: >- The natural-language query could not be translated safely. No credits are charged. content: application/json: schema: $ref: '#/components/schemas/Error' security: - ApiKeyAuth: [] components: schemas: QueryValidationError: type: object description: >- Returned when a company-search query filter fails validation (invalid enum, unknown key, empty query). properties: error: type: string description: What went wrong. field: type: string description: >- JSON path to the bad filter, e.g. query.industry or query.headcountGrowth.timespan. invalid_values: type: array items: type: string description: Values you sent that were rejected. accepted_values: type: array items: type: string description: >- Full list of allowed values for that field (industry, type, or timespan). required: - error - field Error: type: object properties: error: type: string description: Human-readable error message. required: - error securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Your Huntr API key. Get one at tryhuntr.com. Pass as x-api-key header on all authenticated requests. ````