> ## 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. # Company Search > Search companies with structured filters or a natural-language semantic query. Returns one paginated page of company rows. ## 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: Contact APIs description: >- Search people and enrich work email, phone, and reverse-email contact fields. - name: Company APIs description: >- Search companies and retrieve company-level attributes such as detected technology stack and active job postings. - name: Research APIs description: >- Research one company, person, team, or focused business question and return a sales-ready answer. Lite, standard, and deep tiers. - name: LinkedIn APIs description: >- LinkedIn URL discovery, company and profile pages, posts, reactions, and comments. - name: X APIs description: X profiles, posts, search results, and thread context. - name: Web APIs description: >- Find, scrape, 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: - Company APIs summary: Company Search description: >- Search companies with structured filters or a natural-language semantic query. Returns one paginated page of company rows. requestBody: required: true content: application/json: schema: type: object 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: 11a180b2-9860-4a13-93cb-f8d42a4b1e18 query: type: object description: >- At least one filter required. Supported filters: home_page_text, bio_li, services, industry, number_of_employees, revenue, country_code, city, company_name, company_url. Exact lookup filters return 422 when values are not accepted. properties: home_page_text: type: object description: Open text search against scraped website copy. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. bio_li: type: object description: >- Open text search against the company LinkedIn About description. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. services: type: object description: Exact service label. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. industry: type: object description: Exact company industry label. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. number_of_employees: type: object description: Exact employee range label. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. revenue: type: object description: Exact revenue range label. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. country_code: type: object description: Exact ISO alpha-2 country code. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. city: type: object description: Open text company city. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. company_name: type: object description: Open text company name. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. company_url: type: string description: >- Single company domain or URL. Do not wrap in include/exclude. additionalProperties: false pagination: type: object description: >- Configurable page size. pagination.size min 1, default 10, max 100. Send pagination.size on the first request and with pagination.token on later pages. Keep the same query between pages. properties: size: type: integer minimum: 1 maximum: 100 default: 10 description: >- Page size for this request. Min 1, default 10, max 100. Huntr returns up to this many companies and charges per row returned. token: type: string description: >- Opaque cursor from the prior response. Omit on the first page. description: >- Choose one company search input: - Natural-language mode: send semantic_query. Add filters only with semantic_query when you need hard constraints. - Structured-filter mode: send query when you already have exact filters, or when paginating with a resolved_query. Do not send query and semantic_query together. examples: semantic: summary: Natural-language company discovery with a hard country filter description: >- Natural-language mode: semantic_query describes the companies to find. filters adds a hard country constraint. value: semantic_query: >- Companies helping hospitals reduce nurse burnout through workflow automation filters: country_code: include: - US pagination: size: 10 structured: summary: Structured company search description: >- Structured-filter mode: query contains exact filters supplied by your code. value: query: industry: include: - Software Development country_code: include: - US number_of_employees: include: - 100 - 249 services: include: - Web Development pagination: size: 10 by_url: summary: By company URL description: >- Structured-filter mode: query can target one exact company domain with company_url. value: query: company_url: stripe.com pagination: size: 10 responses: '200': description: Company search results. content: application/json: schema: type: object properties: success: type: boolean request_id: type: string result: type: object properties: companies: type: array description: Matching companies. items: type: object properties: company_name: type: string description: Company display name. company_url: type: string description: Company website/domain returned by QuickEnrich. email_domain: type: string description: Company email domain when available. final_email_domain: type: string description: Final normalized email domain when available. home_page_email: type: string description: Email address found on the company home page. phone: type: string description: Company phone number when available. linkedin_url: type: string description: LinkedIn company page URL. city: type: string description: Company city. region_code: type: string description: State/province/region code. country_code: type: string description: ISO 2-letter country code. industry: type: string description: Company industry label. employee_count: type: string description: Company employee size range label. revenue: type: string description: Company revenue range label. services: type: array items: type: string description: Company service labels. service_count: type: integer description: Number of service labels returned. home_page_text: type: string description: Full extracted website text when available. home_page_text_snippet: type: string description: Snippet matched from website text. bio_li_snippet: type: string description: Snippet matched from LinkedIn About text. additionalProperties: true pagination: type: object required: - size - token - has_more properties: size: type: number description: >- Number of companies returned in result.companies for this response page. token: type: string description: >- Opaque token for the next page. Null means there is no next page. nullable: true has_more: type: boolean description: >- Whether another page is available. When false, pagination.token is null. additionalProperties: false total: type: number description: >- Total matching records for the submitted query. This can be larger than the number returned in this page. price: type: number description: Plan-specific amount multiplied by companies returned. credits_remaining: type: number required: - success - request_id - result - price - credits_remaining - pagination - total examples: found: summary: Companies returned value: success: true request_id: req_1746123456_cs1x2y result: companies: - company_name: Acme Cloud Solutions company_url: acme.com email_domain: acme.com final_email_domain: acme.com phone: +1-555-0100 linkedin_url: https://linkedin.com/company/acme city: Austin region_code: TX country_code: US industry: Software Development employee_count: 100 - 249 revenue: 10 - 20 Million services: - Web Development service_count: 1 home_page_text: >- We help enterprises modernize with cloud migration and DevOps. home_page_text_snippet: >- We help enterprises modernize with cloud migration... bio_li_snippet: Leading cloud solutions provider... pagination: size: 1 token: opaque-next-page-token has_more: true total: 842 price: 0.0003 credits_remaining: 4.9997 '400': description: >- Empty query, unknown filter key, invalid filter shape, or invalid pagination token. content: application/json: schema: $ref: '#/components/schemas/QueryValidationError' example: error: 'Unknown query filter(s): domain' field: query invalid_values: - domain accepted_values: - home_page_text - bio_li - services - industry - number_of_employees - revenue - country_code - city - company_name - company_url '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' '422': description: >- A constrained lookup filter contains a value outside the accepted list. content: application/json: schema: $ref: '#/components/schemas/QueryValidationError' example: error: industry contains value(s) outside the allowed lookup list field: query.industry invalid_values: - SaaS accepted_values: - Software Development '500': description: Search failed. 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: [] x-codeSamples: - lang: Shell label: Semantic query source: |- curl --request POST \ --url https://api.tryhuntr.com/company-search \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "semantic_query": "Companies helping hospitals reduce nurse burnout through workflow automation", "filters": { "country_code": { "include": [ "US" ] } }, "pagination": { "size": 10 } }' - lang: Shell label: Structured filters source: |- curl --request POST \ --url https://api.tryhuntr.com/company-search \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "query": { "industry": { "include": [ "Software Development" ] }, "country_code": { "include": [ "US" ] }, "number_of_employees": { "include": [ "100 - 249" ] }, "services": { "include": [ "Web Development" ] } }, "pagination": { "size": 10 } }' - lang: Shell label: Company URL filter source: |- curl --request POST \ --url https://api.tryhuntr.com/company-search \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "query": { "company_url": "stripe.com" }, "pagination": { "size": 10 } }' x-code-samples: - lang: Shell label: Semantic query source: |- curl --request POST \ --url https://api.tryhuntr.com/company-search \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "semantic_query": "Companies helping hospitals reduce nurse burnout through workflow automation", "filters": { "country_code": { "include": [ "US" ] } }, "pagination": { "size": 10 } }' - lang: Shell label: Structured filters source: |- curl --request POST \ --url https://api.tryhuntr.com/company-search \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "query": { "industry": { "include": [ "Software Development" ] }, "country_code": { "include": [ "US" ] }, "number_of_employees": { "include": [ "100 - 249" ] }, "services": { "include": [ "Web Development" ] } }, "pagination": { "size": 10 } }' - lang: Shell label: Company URL filter source: |- curl --request POST \ --url https://api.tryhuntr.com/company-search \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "query": { "company_url": "stripe.com" }, "pagination": { "size": 10 } }' 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.