---
ref: tool:clay/search-people-and-companies
name: Search people and companies
company: company:clay
workflows: [workflow:job-posting-lead-lists]
access: [cli, api]
tags: [capability:find-prospects, 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-29
---

# 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.

Note: Read the query reference first (`GET /search/query-mode/reference`), then page 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 and sign in with it, 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 anything else, confirm access with the cheapest read-only call, like a list or a search. Never send or change anything to test access.

## Rules

- Ask the user before anything that sends messages, costs money, or changes data, and say how many records it touches. One approval covers a batch the user has seen.
- Never print API keys.