Saved searches
Re-run a company or people search on a schedule and track who joins, departs, or stays — you're billed only for what's new.
Saved searches
We built saved searches so a search you care about doesn't go stale the day after you run it. Save the filters once, pick a cadence, and we re-run the search for you (company-only, people-only, or combined) and hand you the delta: who's new, who left, who's still there. You pay only for results you've never seen before.
How a run works
Every run re-executes your saved filters and compares the results against everything the search has ever seen. Each company or person comes out with a movement status:
| Status | Meaning | Billed? |
|---|---|---|
| Joined | Matched for the first time ever | Yes — this is the only billed status |
| Departed | Matched before, doesn't anymore | No |
| Returned | Left at some point, matches again | No |
| Stayed | Still matching | No |
- Only new results cost credits, and a per-run cap bounds the spend:
maxNewCompaniesPerRun/maxNewProfilesPerRun(default 1,000 each, max 10,000, fixed at creation). The cap limits how many new results are revealed and billed — the movement tracking itself always stays complete, so nothing is lost when a run finds more than the cap. - When a run finds more new results than the cap, the ones revealed are the
first in search order. A filter-only search has no inherent order, so set
sorton the saved search if you care which ones come first (newest funding, biggest headcount, and so on). - Newly joined people come back with freshly enriched profile data.
- Results live in the saved search itself — a run doesn't create an audience or list. Read them through the API (below).
- When a run finishes you get a
saved_search.run_completedwebhook with the movement counts, plus an email and an in-app notification.
Scheduling and control
- Cadence:
spawnFrequencyDays, 7–365 days. A scheduled run fires once the previous completed run is older than the frequency. - Heads-up before scheduled runs: a
saved_search.run_upcomingwebhook and email arrive roughly a day ahead, so you can skip the next run (free) if the timing is wrong. A skip pushes the next run one full cycle, and undoing it cancels the skip. - Run on demand: a manual run starts immediately (rejected if another run started within the last 5 minutes).
- Pause: set
isActive: false— no new runs, nothing deleted, flip back anytime. Deleting a saved search is done from the dashboard; there's no delete endpoint.
Out of credits? The run steps aside. A scheduled run with no credit balance is rejected before doing any work — status "No funds", an email lets you know, and nothing is charged. The search stays active and the next cycle runs normally once you top up.
Reading results
All read endpoints are free (cursor pagination, pageSize 1–100,
default 25):
- Per run: the per-run reads return one run's profiles and companies,
with a
statusesfilter. Ask forJOINEDand you get exactly the new arrivals; the usual integration loop is: receiverun_completed, fetch the joined set, feed it to your pipeline. - Current membership: the current-membership reads return everyone currently matching (joined, returned, and stayed).
The run_completed webhook carries counts only, not entities — pair it with
the read endpoints for the records themselves.
What you can call
All operations are POST under /v1/saved-search/…; each operation name
links to its full reference.
| Operation | Path | Notes |
|---|---|---|
createSavedSearch | /create | Name, search params (company / people / combined), spawnFrequencyDays, optional per-run caps. Creates and immediately runs the first search |
updateSavedSearch | /update | Change name, frequency, filters, or isActive; the per-run caps are fixed at creation |
getSavedSearch / listSavedSearch | /get, /list | Configuration, caps, and past run dates |
manuallySpawnSavedSearchRun | /spawn | Run now (5-minute re-trigger guard) |
skipNextSavedSearchRun / undoSkipNextSavedSearchRun | /skip-next-run, /undo-skip | Free; skip exactly one scheduled cycle |
getSavedSearchRun / getLatestSavedSearchRun / getSavedSearchRunStatus / listSavedSearchRuns | /run/get, /run/get-latest, /run/status, /run/list | Run records, movement counts, statuses |
getSavedSearchRunProfiles / getSavedSearchRunCompanies | /run/profiles, /run/companies | Free; one run's results, filterable by movement status |
getCurrentProfilesInSavedSearch / getCurrentCompaniesInSavedSearch | /current/profiles, /current/companies | Free; the full current membership |
Rate limits: creating a saved search or triggering a manual run allows 10 requests per minute; every other saved-search call allows 120.
To see how many companies or people are in a saved search right now, read its current membership (free).
The filters a saved search stores are the same schemas as company and people search — anything you can search, you can save.
In the dashboard
The Saved Searches page shows every search with its frequency, next run, counts, and an Active toggle; the detail view lists run history with joined/departed/stayed columns per entity type. In the dashboard you create a saved search from an existing audience (its filters are copied in) and set the name and frequency. The API is a superset: direct filter control, custom per-run caps, manual runs, and skip controls are API-only.
A dynamic tracker list keeps its own membership fresh. You don't need to create a saved search for it, and it won't appear in your saved-search list.
Using it effectively
- Size the cap to your downstream capacity. If your team can work 500 new accounts a week, cap the run at 500; the rest of the movement picture stays intact, and you're never billed past what you can use.
- Integrate on the webhook.
run_completed→ fetchJOINED→ route to your CRM or sequencer. Counts in the webhook tell you whether it's worth fetching at all. - Skip, don't pause, for a one-off break — a skip keeps the schedule; a pause needs you to remember to come back.
- Start narrow. The first run bills every match as new (that's your baseline). Tighten filters with free count endpoints before saving.
Use cases
- Market-entry watch: save your ICP filters and get the companies that newly qualify each week — new funding, new headcount band, new geography.
- Competitor-driven sourcing: a people search on a competitor's senior titles; every run surfaces who joined or left since last time.
- Territory churn: current-membership reads give account teams a living list of who's in-segment right now, not a quarterly snapshot.
Credits
Runs bill per newly-joined result: 2 credits per new company and 2 per
new person at the standard rate, capped by the per-run limits, after the
run completes. Departed, returned, and stayed entities are never billed, and
neither are re-runs over known ground. Reads, skips, and the searches
themselves are free. chargeInfo on responses is the authoritative record;
org-specific pricing may differ. See Billing & credits.
Exclusion lists
Keep customers, competitors, and past contacts out of every search — free lists of companies or people that filter your results automatically.
Social media APIs
Pull live profiles, posts, audiences, transcripts, and search across X, GitHub, YouTube, Instagram, TikTok, and Reddit — then turn a handle into a contactable person.