> ## 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 Profiles
> Search for profiles using OpenSearch DSL queries. Returns a list of profile IDs that can be passed to the Fetch Profile endpoint.
The Search Profiles endpoint searches the profile database based on attributes using OpenSearch DSL.
See [OpenSearch Mapping](/docs/enrichment-data/profile/mappings-v3) for available fields.
Search returns up to **1000 results per page**.
Replace `"query"` with your OpenSearch DSL query. The response contains a list of profile IDs that can be used in the [Fetch Profile](/docs/endpoints/v3/fetch-profile) endpoint.
```json Response example theme={null}
{
"ids": [
"00007d1c-a048-480a-8c14-1f33a161a3db",
"0000ad61-2eda-4061-a20e-793d41016f03"
],
"total_count": 125867,
"pagination_token": "eyJzZWFyY2hfYWZ0ZXIiOlt7ImZpZWxkIjoiX3Njb3JlIiwidmFsdWUiOjF9LHsiZmllbGQiOiJwcm9maWxlX2luZm8uaWQiLCJ2YWx1ZSI6IjAwMDE2MTU4LWYyY2EtNDYzZC05YWEzLTIyOWZkMzk0ZWQ0MSJ9XX0="
}
```
For query examples, see [Search endpoint examples](/docs/examples/search-endpoint). For a reference on AND/OR, exact phrase matching, and other operators, see [Query operators](/docs/examples/query-operators).
## 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:
```
* **With the header** — the search is scoped to the child team's context.
* **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/profiles/search \
-H "x-api-key: YOUR_API_KEY" \
-H "x-authenticate-team: child-team-id-123" \
-H "Content-Type: application/json" \
-d '{
"query": {
"match": {
"profile_info.job_title": { "query": "Data Scientist" }
}
},
"limit": 10
}'
```
### Pagination
The response includes a `pagination_token` to fetch the next page. See [Pagination](/docs/api-reference/pagination) for full details. The `from` parameter must be `>= 0`.
**Migrating from v2?** v3 uses snake\_case for all field names. The v2 equivalents were `paginationToken`, `totalCount`, and `inNetworkOnly`. See the [Migrating to v3](/docs/getting-started/migrating-to-v3) guide.
## OpenAPI
````yaml openapi.json POST /v3/profiles/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/profiles/search:
post:
tags:
- profiles
summary: Search for profiles ids
description: >-
Search for profiles ids using the [ElasticSearch Query
DSL](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html)
format
operationId: searchProfilesV3
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/profile-v2)
example:
match:
profile_info.job_title:
query: Data Scientist
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
in_network_only:
type: boolean
description: >-
When set to true, restricts search results to profiles that
are connected to your team's network. This parameter filters
the query to only return profiles that have established
connections with connectors of your organization.
default: false
required:
- query
responses:
'200':
description: A list of profile ids matching provided query
content:
application/json:
schema:
type: object
properties:
ids:
description: List of profile ids
type: array
items:
type: string
format: uuid
total_count:
description: Total number of profiles 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
````