Skip to main content
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 the ones added since you last looked.

​
How it works

There are two ways to get a saved search the API can read. From the API. Run AI search, take the query_id it returns, and pass it to Create saved search with a name. The search is shared with the API and your organization on creation, so it is readable immediately. From the app. Build the search in the relevant feed, save it as a named search, then open the saved-searches index, click the three-dot menu (⋯) next to it, and turn on “Share to API”. A search shared only within your team is not reachable. Either way, Get all saved searches lists every search the API can see, with its product type and query ID, and you then call the matching “results” endpoint for that product. To change a search’s filters, edit it in the app. The API can create, read and delete a saved search, but not update one.
New to saved searches? Follow the step-by-step walkthrough for building and managing them in the app in the Saved Searches guide in the Specter Help Center.

​
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. Get a saved search. Create one with Create saved search, or save and share one 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. Pass new_results_after with the timestamp of your last read to get only what has been added since — you choose the window, so a scheduled job never double-reads or skips. Every product’s results endpoint takes it.
  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 by ID, Get investor by ID, or the relevant signal endpoint.

​
Good to know

  • The API can create, read, query and delete a saved search, but not update one. Editing filters is done in the app.
  • A search is reachable when it was created by the API, explicitly shared to the API via “Share to API”, or is a global search curated by Specter. A search shared only within your team is not accessible from the API.
  • A search created through the API is assigned to an organization admin, returned as owner_id, and is visible to your team in the app.
  • new_results_after (every product) restricts results to what was added to the search from that moment on. Additions are tracked for 60 days; an older cutoff returns 422 rather than a partial answer.
  • Results are paginated; empty results are valid, not an error.
  • Unknown or non-visible searches return 404.