> ## Documentation Index
> Fetch the complete documentation index at: https://docs.extruct.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> Find companies from a natural-language query and optional filters.

# Search Companies

<Note>
  **Prefer [`POST /v1/companies/search`](/api-reference/search-post).** This `GET` endpoint is deprecated. It still works and returns identical results, but POST is the recommended default: it takes `filters` as a JSON object and is not limited by URL length (required for large `exclude.domains` lists).
</Note>

## Overview

Semantic Search returns companies that match a natural-language query, with optional firmographic filters.
It is the recall-first search endpoint over the Extruct index and the usual starting point before lookalike or Deep Search.

## Example request

```bash theme={null}
export EXTRUCT_API_TOKEN="YOUR_API_TOKEN"

curl --get "https://api.extruct.ai/v1/companies/search" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  --data-urlencode "q=b2b treasury automation" \
  --data-urlencode 'filters={"include":{"country":["United States"],"size":["51-200","201-500"]},"range":{"founded":{"min":2018}}}' \
  --data-urlencode "offset=0" \
  --data-urlencode "limit=20"
```

## Key parameters

* `q` (required): Natural-language query.
* `filters` (optional): JSON string used to narrow results.
* `offset` (optional): Pagination offset.
* `limit` (optional): Page size, up to `250` per request.

For supported `filters`, see [Search Filters Reference](/api-guides/search/search-filters-reference).

## Endpoint behavior

* Results are ranked by semantic match in the Extruct index.
* `filters` narrow the candidate set; they do not replace the query.
* A single request returns at most `250` results. Page with `offset` to read deeper: paid plans (Starter, Pro) can reach up to `2,000` results per query; the free tier is capped at `25`.
* Good matches from search often become inputs for [Company Lookup](/api-reference/company-lookup), seed companies for [Lookalike Search](/api-reference/lookalike-search), or a shortlist for [Deep Search](/api-reference/discover/create-company-discovery-task).

## Success signal

A successful response returns `results` and request metadata. Reuse `results[].id` or `results[].domain` as downstream identifiers, including company lookup and lookalike input.

## Common errors

### `401 Unauthorized`

Check that your header is `Authorization: Bearer ${EXTRUCT_API_TOKEN}`.

### `422 Unprocessable Entity`

Most often caused by malformed `filters` JSON. Validate before sending:

```bash theme={null}
echo '<filters-json>' | jq empty
```

## Related endpoints

* [Company Lookup Endpoint](/api-reference/company-lookup)
* [Lookalike Search Endpoint](/api-reference/lookalike-search)

## Related guides

* [Semantic Search](/api-guides/search/semantic-search)
* [Lookalike Search](/api-guides/search/lookalike-search)


## OpenAPI

````yaml GET /v1/companies/search
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security: []
paths:
  /v1/companies/search:
    get:
      tags:
        - search
      summary: Search Companies
      description: >-
        Find companies using a natural-language query. Use `filters` (JSON
        string) to narrow results by size, country, city, and founded year
        range.
      operationId: search_companies_v1_companies_search_get
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
            description: Search query
            title: Q
          description: Search query
        - name: filters
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              JSON string of SearchFilters. Supported keys only:
              include.size/country/city, exclude.size/country/city/domains,
              range.founded.min/max.
          description: >-
            JSON string of SearchFilters. Supported keys only:
            include.size/country/city, exclude.size/country/city/domains,
            range.founded.min/max.
          example: >-
            {"include":{"country":["United
            States"],"size":["51-200"]},"range":{"founded":{"min":2018}}}
        - name: offset
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
        - name: limit
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanySearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      deprecated: true
      security:
        - HTTPBearer: []
components:
  schemas:
    CompanySearchResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/CompanySearchResult'
          type: array
          title: Results
          description: Search results
        request:
          $ref: '#/components/schemas/SearchRequestInfo'
          description: Request parameters echo
      type: object
      required:
        - results
        - request
      title: CompanySearchResponse
      description: Semantic search response wrapper.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CompanySearchResult:
      properties:
        id:
          type: string
          title: Id
          description: Company ID
        domain:
          type: string
          title: Domain
          description: Company domain
        name:
          type: string
          title: Name
          description: Company name
        short_description:
          anyOf:
            - type: string
            - type: 'null'
          description: Brief company description
        full_description:
          anyOf:
            - type: string
            - type: 'null'
          description: Detailed company description
        products_services:
          anyOf:
            - type: string
            - type: 'null'
          description: Products and services offered
        use_cases:
          anyOf:
            - type: string
            - type: 'null'
          description: Use cases for products/services
        target_audience:
          anyOf:
            - type: string
            - type: 'null'
          description: Target customer audience
        other_considerations:
          anyOf:
            - type: string
            - type: 'null'
          description: Additional considerations
        founding_year:
          anyOf:
            - type: integer
            - type: 'null'
          description: Year company was founded
        employee_count:
          anyOf:
            - type: string
            - type: 'null'
          description: Employee count range
        hq_country:
          anyOf:
            - type: string
            - type: 'null'
          description: Headquarters country
        hq_state_province:
          anyOf:
            - type: string
            - type: 'null'
          description: Headquarters state/province
        hq_city:
          anyOf:
            - type: string
            - type: 'null'
          description: Headquarters city
        hq_full_address:
          anyOf:
            - type: string
            - type: 'null'
          description: Full headquarters address
        social_profiles:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          description: Social media profiles
        website_authority:
          anyOf:
            - $ref: '#/components/schemas/WebsiteAuthority'
            - type: 'null'
          description: Website authority metrics
        relevance_score:
          anyOf:
            - type: number
            - type: 'null'
          description: Relevance score (0-1)
      type: object
      required:
        - id
        - domain
        - name
      title: CompanySearchResult
      description: Individual company search result.
    SearchRequestInfo:
      properties:
        query:
          anyOf:
            - type: string
            - type: 'null'
          description: Search query text
        offset:
          type: integer
          title: Offset
          description: Result offset
        limit:
          type: integer
          title: Limit
          description: Results limit
        filters:
          anyOf:
            - $ref: '#/components/schemas/SearchFilters'
            - type: 'null'
          description: Applied filters (SearchFilters object).
      type: object
      required:
        - offset
        - limit
      title: SearchRequestInfo
      description: Search request parameters.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    WebsiteAuthority:
      properties:
        score:
          type: integer
          title: Score
          description: Authority score (0-100)
        tier:
          type: string
          title: Tier
          description: Authority tier classification
        tier_label:
          type: string
          title: Tier Label
          description: Human-readable tier label
      type: object
      required:
        - score
        - tier
        - tier_label
      title: WebsiteAuthority
      description: Website authority scoring details.
    SearchFilters:
      type: object
      title: SearchFilters
      description: Structured filters for search and lookalike endpoints.
      additionalProperties: false
      properties:
        include:
          $ref: '#/components/schemas/SearchFiltersInclude'
        exclude:
          $ref: '#/components/schemas/SearchFiltersExclude'
        range:
          $ref: '#/components/schemas/SearchFiltersRange'
    SearchFiltersInclude:
      type: object
      title: SearchFiltersInclude
      description: Include companies that match these values.
      additionalProperties: false
      properties:
        size:
          type: array
          items:
            $ref: '#/components/schemas/CompanySize'
          description: Employee size buckets to include.
        country:
          type: array
          items:
            type: string
          description: Headquarters countries to include.
        city:
          type: array
          items:
            type: string
          description: Headquarters cities to include.
    SearchFiltersExclude:
      type: object
      title: SearchFiltersExclude
      description: Exclude companies that match these values.
      additionalProperties: false
      properties:
        size:
          type: array
          items:
            $ref: '#/components/schemas/CompanySize'
          description: Employee size buckets to exclude.
        country:
          type: array
          items:
            type: string
          description: Headquarters countries to exclude.
        city:
          type: array
          items:
            type: string
          description: Headquarters cities to exclude.
        domains:
          type: array
          items:
            type: string
          description: >-
            Company domains or URLs to exclude from results. Normalized to the
            registered domain server-side; alias-aware; max 1000.
    SearchFiltersRange:
      type: object
      title: SearchFiltersRange
      description: Numeric range constraints.
      additionalProperties: false
      properties:
        founded:
          $ref: '#/components/schemas/FoundedYearRange'
          description: Filter companies by founding year range.
    CompanySize:
      type: string
      enum:
        - 1-10
        - 11-50
        - 51-200
        - 201-500
        - 501-1000
        - 1001-5000
        - 5001-10000
        - 10001+
      title: CompanySize
      description: Employee headcount buckets using LinkedIn-style ranges.
    FoundedYearRange:
      type: object
      title: FoundedYearRange
      description: Inclusive range bounds for founding year.
      additionalProperties: false
      properties:
        min:
          type: integer
          description: Minimum founding year (inclusive).
        max:
          type: integer
          description: Maximum founding year (inclusive).
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````