Start Find Search
start_find_searchKick off an Exa Websets search for a named list on an agent.
An agent can host many named lists. Each list spawns its own Exa webset, so distinct criteria buckets (e.g. 'oil & gas operators' vs 'midstream') don't share Exa's per-webset domain-dedup.
Costs 2 Sliq credits per ingested result (charged during ingest). Free when the user has their own Exa key connected.
Refuses to start when the balance can't afford even one result in
sliq_credits mode. When the balance covers fewer results than requested,
the count is clamped to what's affordable and the result carries a
clamp_notice — surface it to the user ("you have X credits, so I'll
find Y").
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | The agent to host the new list. | |
| criteria | Yes | what to search for (the Exa query body). | |
| excluded | No | company domains/URLs the webset must not ingest (matched by domain). Use to avoid re-ingesting rows already recorded in the list, e.g. seeds from find_companies_by_tech_stack. | |
| list_name | Yes | short kebab slug identifying the bucket (e.g. 'oil-gas-operators'). Pick a name distinct from any existing list on the agent. Re-using a finished list's name extends it; re-using a running list's name is refused. | |
| entity_type | Yes | 'person' or 'company'. Mixed people+company agents are supported — each list has its own row type. | |
| max_results | No | target count (capped at the per-list provider cap). | |
| on_behalf_of | No | An agency client's email, from list_agency_clients, to run this call in that client's account: their agents, settings, connected accounts, and credits. Omit it to act on your own account. | |
| people_query | No | For company lists, a positive-form query for the people to find at each new company that the check against `criteria` doesn't reject — controls which people come back. They're saved as person rows on the '<list_name>-people' list when the search finishes. Company lists only; skipped on person lists. | |
| people_titles | No | The roles `people_query` is asking for, as title keywords, e.g. ['Marketing', 'Growth'] or ['Operations', 'Chief']. Each is matched as a case-insensitive substring of a person's job title and the list is OR-ed, so use the distinctive word a title is built from rather than a whole title: companies word the same job many ways, and a full phrase finds only the ones that word it exactly as written here. Broader words recall more people and admit more adjacent roles, so pick the narrowest word that still covers the variants. Set it whenever `people_query` names roles — the people search runs unattended, so this is its only structured read of the roles you asked for. Company lists only. | |
| people_preferences | No | Soft preferences and exclusions for the people found. Each is checked against them, where only an exclusion rules someone out. Company lists only. | |
| people_exclude_titles | No | Title keywords to reject, e.g. ['Coordinator', 'Intern']. Same substring matching as `people_titles`, subtracted from it. Whenever `people_preferences` rules a role out, put that role here too — an exclusion written only there applies after the fetch, so the excluded people can still fill the fetched slots. Company lists only. | |
| people_include_alumni | No | Include past employees (alumni) alongside current ones in the people search (default false). Company lists only. |