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:

• 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.
• 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_completed webhook 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_upcoming webhook and email arrive roughly a day ahead, so you can skipNextSavedSearchRun (free) if the timing is wrong — it pushes the next run one full cycle, and undoSkipNextSavedSearchRun cancels the skip.
• Run on demand: manuallySpawnSavedSearchRun starts a run 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.

Reading results

All read endpoints are free (cursor pagination, pageSize 1–100, default 25):

• Per run — getSavedSearchRunProfiles / getSavedSearchRunCompanies return one run's results, with a statuses filter. Ask for JOINED and you get exactly the new arrivals — the usual integration loop is: receive run_completed, fetch the joined set, feed it to your pipeline.
• Current membership — getCurrentProfilesInSavedSearch / getCurrentCompaniesInSavedSearch 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.

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.

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 → fetch JOINED → 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.