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

# Search with advanced queries (beta)

> Find Clay companies or people with Clay's advanced search query language.

Advanced search is in beta. It supports criteria from Clay's field catalog as well as cross-entity filters and nested Boolean logic.

Advanced queries return either people or companies. Count queries and job searches are not available through the Public API.

## Get the query reference

Fetch the query reference before writing a query. It describes the available fields and grammar.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request GET \
  --url https://api.clay.com/public/v0/search/query-mode/reference \
  --header "clay-api-key: $CLAY_PUBLIC_API_KEY"
```

## Create and run a people search

This pattern returns current software engineers whose employer is in the Software Development industry.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
QUERY='select from people where experiences.any('\
'is_current = true and '\
'job_title is_similar_to ("software engineer") and '\
'company.industry = "Software Development")'

SEARCH_ID=$(curl --request POST \
  --url https://api.clay.com/public/v0/search/query-mode \
  --header "Content-Type: application/json" \
  --header "clay-api-key: $CLAY_PUBLIC_API_KEY" \
  --data "$(jq -n --arg query "$QUERY" '{query: $query}')" \
  | jq -r '.search_id')

curl --request POST \
  --url "https://api.clay.com/public/v0/search/query-mode/$SEARCH_ID/run" \
  --header "Content-Type: application/json" \
  --header "clay-api-key: $CLAY_PUBLIC_API_KEY" \
  --data '{"limit": 20}'
```

## Use cross-entity query patterns

Choose the record type you want returned, then query through its relationships.

### Find people based on their employer

Use `experiences.any(...)` to return people whose current employer meets your criteria.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
select from people
where experiences.any(
  is_current = true and
  job_title is_similar_to ("engineer") and
  company.technographics.any(vendor = "Salesforce")
)
```

### Find companies based on their employees

Use `people.exists(...)` to return companies that employ people matching your criteria.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
select from companies
where people.exists(
  is_current = true and
  job_title is_similar_to ("VP Sales")
)
```

### Combine criteria with Boolean logic

Group related criteria with parentheses to express alternatives while keeping the company requirement.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
select from people
where experiences.any(
  is_current = true and
  (
    job_title is_similar_to ("VP Sales") or
    job_title is_similar_to ("Head of Sales")
  ) and
  company.estimated_employee_count >= 500
)
```

## Fetch more results

The run endpoint is a stateful iterator. Its response contains `data`, `has_more`, and `source_type`, and can include `exhaustion_reason`. If `has_more` is `true`, call `POST /search/query-mode/{search_id}/run` again to fetch the next page.

People results include a structured location and an array of experiences that matched the query. `matched_experiences` is always an array; it is empty when no specific experience matched.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": [
    {
      "clay_profile_id": 42,
      "name": "Jane Doe",
      "first_name": "Jane",
      "last_name": "Doe",
      "location": {
        "name": "New York, New York, United States",
        "city": "New York",
        "state_or_province": "New York"
      },
      "matched_experiences": [
        {
          "company": "Example Corp",
          "title": "Software Engineer",
          "location": "New York, New York, United States",
          "start_date": "2024-01-01",
          "end_date": null
        }
      ]
    }
  ],
  "has_more": true,
  "source_type": "people"
}
```

Company results use their own projection, including `clay_company_id`, `name`, `size`, `type`, `domain`, `country`, `industry`, `location`, `description`, `linkedin_url`, `annual_revenue`, and `total_funding_amount_range_usd`.

## Next steps

<Card title="Structured filters" href="/searches/filters">
  Use the older JSON filters format.
</Card>