Search people and companies

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.

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.