Skip to content
Docs

Run Saved Search

Count the current matches of a saved search. Free.

POST/api/v1/lead-finder/saved-searches/{saved_search_id}/run

Requires an API key with the write scope.

Free: no reveal credits and no search budget are spent. FoxReach asks the data provider for a count with the stored filters and updates the saved total and last-run time. It returns the count, not the people; use Search People with the same filters to fetch them. The write scope is needed because the stored total changes.

Path Parameters#

saved_search_idstringpathrequired
The saved search id.

Response#

dataobject
Show data
totalinteger
Current number of matches.
lastRunAtstring
ISO 8601 timestamp of this run.

Errors#

StatusDescription
401Missing, invalid, revoked or expired API key
403API key does not have the required scope: write
402upgrade_required on the Free plan
404Lead Finder is not enabled while Lead Finder is switched off on this environment
503Lead Finder is not configured when it is enabled but has no data provider key
404Saved search not found: it does not exist in this workspace
502The data provider is unavailable right now

Rate Limit#

  • 100 requests per minute, shared by every expensive call in your workspace. Fixed 60-second window.
  • Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unix epoch seconds) and X-RateLimit-Bucket (expensive).
  • A 429 response includes a Retry-After header (seconds until the bucket resets).

For client-side patterns, see Rate Limiting.

Was this page helpful?
View as MarkdownLast updated November 4, 2026