> ## Documentation Index
> Fetch the complete documentation index at: https://api.tryspecter.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Saved Searches

> Turn filters you've built in the Specter app into a live, queryable feed

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](/api-reference/saved-searches/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.

<Info>
  New to saved searches? Follow the step-by-step walkthrough for building and managing them in the app in the [Saved Searches guide](https://intercom.help/specter-labs/en/collections/6581526-saved-searches) in the Specter Help Center.
</Info>

## Endpoints

### Discover and manage

| Method   | Endpoint                                                                       | Returns                                                  |
| -------- | ------------------------------------------------------------------------------ | -------------------------------------------------------- |
| `GET`    | [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches) | Every saved search shared with the API, across all types |
| `DELETE` | [Delete a search](/api-reference/saved-searches/delete-a-search)               | Permanently deletes a saved search (irreversible)        |

### Details and results (by product type)

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

| Method | Endpoint                                                                                                                                                 | Returns                              |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `GET`  | [Get company saved search details](/api-reference/company-saved-searches/get-company-saved-search-details)                                               | Match counts for a company search    |
| `GET`  | [Get company saved search results](/api-reference/company-saved-searches/get-company-saved-search-results)                                               | The companies matching the search    |
| `GET`  | [Get people saved search details](/api-reference/people-saved-searches/get-people-saved-search-details)                                                  | Match counts for a people search     |
| `GET`  | [Get people saved search results](/api-reference/people-saved-searches/get-people-saved-search-results)                                                  | The people matching the search       |
| `GET`  | [Get investor saved search details](/api-reference/investor-saved-searches/get-investor-saved-search-details)                                            | Match counts for an investor search  |
| `GET`  | [Get investor saved search results](/api-reference/investor-saved-searches/get-investor-saved-search-results)                                            | The investors matching the search    |
| `GET`  | [Get Talent Signals saved search details](/api-reference/talent-signals-saved-searches/get-talent-signals-saved-search-details)                          | Match counts for a talent search     |
| `GET`  | [Get Talent Signals saved search results](/api-reference/talent-signals-saved-searches/get-talent-signals-saved-search-results)                          | Talent signals matching the search   |
| `GET`  | [Get Investor Interest Signals saved search details](/api-reference/investor-interest-saved-searches/get-investor-interest-signals-saved-search-details) | Match counts for an interest search  |
| `GET`  | [Get Investor Interest Signals saved search results](/api-reference/investor-interest-saved-searches/get-investor-interest-signals-saved-search-results) | Interest signals matching the search |

## 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](/api-reference/saved-searches/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](/api-reference/companies/get-company-by-id), [Get person info by ID](/api-reference/people/get-person-info-by-id), [Get investor by ID](/api-reference/investors/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`.