Saved Searches

A saved search turns a set of filters you’ve built in the Specter app into a live, queryable feed. Save the search once, share it with the API, and pull its matching companies, people, investors, or signals on demand — including just this week’s new matches.

​

How it works (app first)

Saved searches are created and edited in the Specter app, not the API. The flow is:

1. Build the search in the app — open the relevant feed (companies, people, investors, talent, or interest), apply your filters, and save it as a named search.
2. Share it with the API — turn on “Share to API” for that saved search. Only searches you have explicitly shared to the API (plus global searches curated by Specter) are reachable; a search shared only within your team or organization is not.
3. Find its ID — Get all saved searches returns every search shared with the API, across all product types, with its query ID and type.
4. Query it — call the matching “results” endpoint for that product type (below).

To change a search’s filters, edit it in the app — the API is read-and-delete only, there is no update endpoint.

​

Endpoints

​

Discover and manage

​

Details and results (by product type)

“Details” gives counts (total matched, newly added, with highlights) cheaply; “results” returns the matching records, paginated.

​

How to use the API

Get started monitoring a search:

1. Save and share a search in the app (see “How it works” above).
2. Find it — Get all saved searches → note the query_id and product type.
3. Pull results — call the matching results endpoint for that type, paginated.
4. Poll for new matches — on Talent and Interest searches, add new=true to return only the current week’s new signals, ideal for a scheduled job.
5. Check counts cheaply — the “details” endpoint returns total matched / newly added without pulling every record — handy for dashboards.

Chain into the rest of the API. Search results carry the underlying IDs — follow them to Get company by ID, Get person info by ID, Get investor by ID, or the relevant signal endpoint.

​

Good to know

• Saved searches are created and edited in the app; the API reads, queries, and deletes them, but does not update them.
• A search must be explicitly shared to the API via “Share to API” (or be a global search curated by Specter) to be reachable. Searches shared only within your team or organization are not accessible from the API.
• new=true (Talent and Interest searches) restricts results to the current week, overriding the search’s stored date filter.
• Results are paginated; empty results are valid, not an error.
• Unknown or non-visible searches return 404.