---
ref: tool:clay/search-people-and-companies
name: Search people and companies
company: company:clay
workflows: []
access: [cli, api]
tags: [capability:build-audience, category:data-provider, has:api, has:cli]
docs: https://developers.clay.com/api-reference/search/create-a-search-from-a-clay-search-query
updated: 2026-09-26
---

# Search people and companies

Starts a search of Clay's database of people or companies from an advanced search query and returns a search id to page through the matches.

Read the query reference first (`GET /search/query-mode/reference`), then
page through results with `POST /search/query-mode/{search_id}/run` while
`has_more` is true. Results per search and per 30 days are capped by plan.

## Set up

Use the first option your agent supports.

### CLI (official)

Install the command, then confirm it runs.

```sh
npm install --global @clay-run/cli
clay --version
```

Run `clay searches query-mode create`.

### API (official)

- Base URL: https://api.clay.com/public/v0
- Endpoint: `POST /search/query-mode`
- Auth: send the header `clay-api-key: $CLAY_PUBLIC_API_KEY`
- Get a key: https://app.clay.com/workspaces/~/settings/account?accountTab=api-keys-beta
- Docs: https://developers.clay.com/public-api/authentication

Before doing anything else, make one read-only call to confirm access.

## Rules

- Ask the user before anything that sends messages, costs money, or changes data.
- Never print API keys.