Running a First Company Search with the Clay CLI

clay searches query-mode finds companies or people with a query string, pages through the results, and did not change the credit balance in any run measured here. A first search takes three commands.

What you will build

A company search for software companies headquartered in the United States, read three records at a time.

clay searches query-mode create --query '<query>'   ->  searchId
    ↓
clay searches query-mode run <searchId> --limit 3   ->  page 1
    ↓
clay searches query-mode run <searchId> --limit 3   ->  page 2 (the iterator advances)

AI Prompt

Using the Clay CLI, search for companies and read two pages of results.

Requirements:
- `clay searches query-mode create --query '<query>'` returns `{ searchId, sourceType }`. Only `select from people` and `select from companies` queries are supported.
- Company location filters use `locations.any(is_headquarters = true and country_name = "<country>")`. Company industry uses `industry = "<value>"`.
- `clay searches query-mode run <searchId> --limit <n>` returns the next page of `n` records (1 to 500, default 20) and advances the iterator, so repeating the call returns the following records.
- The response includes `data`, `hasMore`, `exhaustionReason`, and `periodQuota`.
- Read `clay credits balance` before and after to confirm the search did not spend credits.
- Run the verification step below before finishing.

Using the Clay CLI, search for companies and read two pages of results.

Requirements:
- `clay searches query-mode create --query '<query>'` returns `{ searchId, sourceType }`. Only `select from people` and `select from companies` queries are supported.
- Company location filters use `locations.any(is_headquarters = true and country_name = "<country>")`. Company industry uses `industry = "<value>"`.
- `clay searches query-mode run <searchId> --limit <n>` returns the next page of `n` records (1 to 500, default 20) and advances the iterator, so repeating the call returns the following records.
- The response includes `data`, `hasMore`, `exhaustionReason`, and `periodQuota`.
- Read `clay credits balance` before and after to confirm the search did not spend credits.
- Run the verification step below before finishing.

Prerequisites

The clay CLI on PATH, authenticated via clay login
jq

Note: JSON samples below are trimmed to the fields relevant to each step. Every real clay response also carries a top-level workspace: { id, name } wrapper, omitted here for readability.

1. Create the search

clay credits balance | jq .balance
Q='select from companies where industry = "Software Development" and locations.any(is_headquarters = true and country_name = "United States")'
clay searches query-mode create --query "$Q"

clay credits balance | jq .balance
Q='select from companies where industry = "Software Development" and locations.any(is_headquarters = true and country_name = "United States")'
clay searches query-mode create --query "$Q"

Real output:

{ "searchId": "search_0tmnzbqMRKuEkrzvTd6", "sourceType": "companies" }

{ "searchId": "search_0tmnzbqMRKuEkrzvTd6", "sourceType": "companies" }

2. Read two pages

SID=search_0tmnzbqMRKuEkrzvTd6
clay searches query-mode run $SID --limit 3 | jq -c '{n: (.data | length), hasMore, names: [.data[].name]}'
clay searches query-mode run $SID --limit 3 | jq -c '{n: (.data | length), hasMore, names: [.data[].name]}'

SID=search_0tmnzbqMRKuEkrzvTd6
clay searches query-mode run $SID --limit 3 | jq -c '{n: (.data | length), hasMore, names: [.data[].name]}'
clay searches query-mode run $SID --limit 3 | jq -c '{n: (.data | length), hasMore, names: [.data[].name]}'

Real output:

{"n":3,"hasMore":true,"names":["Google","Amazon","LinkedIn"]}
{"n":3,"hasMore":true,"names":["Microsoft","Meta","Cisco"]}

{"n":3,"hasMore":true,"names":["Google","Amazon","LinkedIn"]}
{"n":3,"hasMore":true,"names":["Microsoft","Meta","Cisco"]}

Each call returned the next three records. The first record of page 2 was not in page 1.

3. Look at one record's fields

clay searches query-mode run $SID --limit 1 | jq -c '.data[0] | keys'

clay searches query-mode run $SID --limit 1 | jq -c '.data[0] | keys'

Real output, for the third page of the same search:

["annual_revenue","clay_company_id","country","description","domain","industry","linkedin_url","location","name","size","total_funding_amount_range_usd","type"]

["annual_revenue","clay_company_id","country","description","domain","industry","linkedin_url","location","name","size","total_funding_amount_range_usd","type"]

4. Confirm the balance

clay credits balance | jq .balance

clay credits balance | jq .balance

Real output:

The balance is the same as before the search, after 7 company records were read (3, 3, and 1) and 5 more in the verification command below.

Verify the result

clay searches query-mode create --query 'select from companies where industry = "Software Development"' | jq -r .searchId | xargs -I{} clay searches query-mode run {} --limit 5 | jq '.data | length'

clay searches query-mode create --query 'select from companies where industry = "Software Development"' | jq -r .searchId | xargs -I{} clay searches query-mode run {} --limit 5 | jq '.data | length'

Expected: 5, with clay credits balance unchanged.

How it works

create registers a query and returns an id. run reads the next page from that id and moves a server-side position forward, so a search is read like a cursor. Records are drawn against a period quota that is reported in each response, not against the credit balance.

Common issues

Field names must come from the reference

A query using country = "United States" on companies returned Unknown field 'country' for entity 'companies'. A people query using job_title contains ... outside an experiences.any(...) scope returned Unknown field 'job_title' for entity 'people'. clay searches query-mode reference lists the fields and the locations.any(...) and experiences.any(...) forms that work.

A query that is not a select statement is rejected

clay searches query-mode create --query 'find me companies' returned Expected SELECT or COUNT but got IDENT (at line 1, col 1). Start the query with select from companies where or select from people where.

The page size has an upper limit

--limit 501 returned --limit must be less than or equal to 500.

Next steps

verification:
  status: verified
  tested_at: "2026-10-09"
  product_version: "clay CLI 1.9.1"
  command: "clay searches query-mode create --query 'select from companies where industry = \"Software Development\"' | jq -r .searchId | xargs -I{} clay searches query-mode run {} --limit 5 | jq '.data | length'"
  expected_result: "5, with the credit balance unchanged."

verification:
  status: verified
  tested_at: "2026-10-09"
  product_version: "clay CLI 1.9.1"
  command: "clay searches query-mode create --query 'select from companies where industry = \"Software Development\"' | jq -r .searchId | xargs -I{} clay searches query-mode run {} --limit 5 | jq '.data | length'"
  expected_result: "5, with the credit balance unchanged."