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

# Search Companies

> Search the company database using OpenSearch DSL queries. Returns a list of company IDs that can be passed to the Fetch Company endpoint.

The Search Companies endpoint searches the internal database of Companies using OpenSearch DSL.

See [OpenSearch Mapping](/docs/enrichment-data/company/mappings-v3) for available fields.

Replace `"query"` with your OpenSearch DSL query and set the `x-api-key` header.

Search returns up to **1000 results per page**. Pagination works the same as the [Search Profiles](/docs/endpoints/v3/search-profiles) endpoint.

```json Response example theme={null}
{
  "ids": [
    "09d9c510-c9f6-4c6e-9e62-fe5fedbeda87"
  ],
  "total_count": 1,
  "pagination_token": "eyJzZWFyY2hfYWZ0ZXIiOlt7ImZpZWxkIjoiX3Njb3JlIiwidmFsdWUiOjF9LHsiZmllbGQiOiJwcm9maWxlX2luZm8uaWQiLCJ2YWx1ZSI6IjAwMDE2MTU4LWYyY2EtNDYzZC05YWEzLTIyOWZkMzk0ZWQ0MSJ9XX0="
}
```

For query examples, see [Search endpoint examples](/docs/examples/search-endpoint).

## Partner teams

Partners can execute a request in the context of a child team by passing the child team's ID in the `x-authenticate-team` header:

```http theme={null}
x-authenticate-team: <child_team_id>
```

* **With the header** — the search runs in the context of the child team.
* **Without the header** — the search runs in the context of the team that owns the API key (default).

The `child_team_id` is returned when you [create a child team](/docs/endpoints/v3/create-team).

```bash Example request theme={null}
curl -X POST https://bee.theswarm.com/v3/companies/search \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-authenticate-team: child-team-id-123" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "match": {
        "company_info.industry": { "query": "Software" }
      }
    },
    "limit": 10
  }'
```

<Note>
  **Migrating from v2?** v3 uses snake\_case for all field names. The v2 equivalents were `paginationToken` and `totalCount`. See the [Migrating to v3](/docs/getting-started/migrating-to-v3) guide.
</Note>


## OpenAPI

````yaml openapi.json POST /v3/companies/search
openapi: 3.1.0
info:
  title: Swarm API
  version: 1.0.0
  contact:
    name: The Swarm
    url: https://theswarm.com
    email: hello@theswarm.com
servers:
  - url: https://bee.theswarm.com
security:
  - ApiKeyAuth: []
tags:
  - name: profiles
    description: Operations related to profiles
  - name: companies
    description: Operations related to companies
  - name: teams
    description: Operations for managing teams and connectors
  - name: social
    description: Operations related to social media posts and interactions
  - name: mcp
    description: Model Context Protocol endpoint for AI assistant integrations
  - name: credits
    description: Operations related to credit usage
  - name: network-mapper
    description: Operations for mapping connections and relationships across your network
paths:
  /v3/companies/search:
    post:
      tags:
        - companies
      summary: Search for companies ids
      description: >-
        Search for companies ids using the [ElasticSearch Query
        DSL](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html)
        format
      operationId: searchCompaniesV3
      parameters:
        - $ref: '#/components/parameters/AuthenticateTeamHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: object
                  description: >-
                    Search query in the [ElasticSearch Query
                    DSL](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html)
                    format. [Find mapping
                    here](https://docs.theswarm.com/docs/mappings/company-v2)
                  example:
                    match:
                      company_info.industry:
                        query: Financial Services
                limit:
                  type: integer
                  description: >-
                    Limit the number of results. If you want to use
                    stable_pagination this parameter must be set to 1000
                  default: 100
                  minimum: 0
                  maximum: 1000
                pagination_token:
                  type: string
                  description: Pagination token received in the previous response
                stable_pagination:
                  type: boolean
                  description: >-
                    When set to true, ensures that pagination results remain
                    consistent, even if the underlying data changes during
                    retrieval. This is useful for retrieving large result sets
                    reliably across multiple requests
                  default: false
              required:
                - query
      responses:
        '200':
          description: A list of company ids matching provided query
          content:
            application/json:
              schema:
                type: object
                properties:
                  ids:
                    description: List of company ids
                    type: array
                    items:
                      type: string
                      format: uuid
                  total_count:
                    description: Total number of companies matching the query
                    type: integer
                  pagination_token:
                    description: Pagination token for the next request
                    type: string
                required:
                  - ids
                  - total_count
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        5XX:
          $ref: '#/components/responses/5XX'
      security:
        - ApiKeyAuth: []
components:
  parameters:
    AuthenticateTeamHeader:
      name: x-authenticate-team
      in: header
      required: false
      description: >-
        Partner accounts only. When present, the request is executed in the
        context of the specified child team (use the `team_id` returned by
        [Create Team](/docs/endpoints/v3/create-team)). When omitted, the
        request runs as the team that owns the API key.
      schema:
        type: string
  responses:
    '400':
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '401':
      description: Unauthorized
    '403':
      description: Forbidden
    5XX:
      description: Unexpected error
  schemas:
    ErrorResponse:
      type: object
      properties:
        code:
          description: Error status code
          type: integer
        errors:
          type: array
          items:
            type:
              - string
              - object
      required:
        - code
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````