> ## 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.

# Get company saved search

> Returns count-level details for a saved company search: total companies matched, newly added, and companies with highlights.

<Note> Free. This call does not consume credits. </Note>

## What you need

A company saved-search ID shared with the API; get one from [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches).

## Behaviour

- Returns counts only (no per-company records); fetch the companies with [Get company saved search results](/api-reference/company-saved-searches/get-company-saved-search-results).
- Filter the counts with `new` (companies first seen in this search), `newGrowthHighlights` (new growth changes), or `newFundingHighlights` (new funding changes).
- The saved search must be shared with the API (via "Share to API") or be a global search curated by Specter.
- `searchId` must be a number, otherwise `400`; returns `404` if the search doesn't exist, and `400` with `NOT_SUPPORTED_PRODUCT` if the search belongs to a non-company product.

## What you do next

- **Pull the companies.** Fetch full records with [Get company saved search results](/api-reference/company-saved-searches/get-company-saved-search-results).




## OpenAPI

````yaml /api-ref/bundle_api.yaml get /searches/companies/{searchId}
openapi: 3.0.0
info:
  title: Specter API
  termsOfService: https://tryspecter.com/terms/
  contact:
    name: API support
    email: api-support@tryspecter.com
  version: 1.0.0
servers:
  - description: Production
    url: https://app.tryspecter.com/api/v1
security:
  - ApiKeyAuth: []
tags:
  - name: Enrich
    description: >
      Look up a company, person, or investor and, if Specter does not already
      hold it, fetch it on demand. Includes email-based person enrichment.
  - name: Search
    description: |
      Find records across every product from a single plain-English query.
  - name: Companies
    description: >
      Company profiles, funding, headcount, traction, the per-company signals
      and sub-resources attached to a single company, and identifier resolution.
  - name: People
    description: >
      Specter people records: profile data, contact details, and per-person
      lookups for a known person ID.
  - name: Investors
    description: >
      Specter investor records: profile, activity, targeting, funds, portfolio
      companies, and the funding rounds they have participated in.
  - name: Transactions
    description: |
      Transaction detail by ID: funding rounds, acquisitions, and IPOs.
  - name: News Signals
    description: |
      Company-level news signals: by ID, and for a saved list or company search.
  - name: Revenue Signals
    description: >
      Revenue and profitability signals: by ID, by date, and for a saved list or
      company search.
  - name: Talent Signals
    description: |
      Talent signals: by ID and in bulk by ID.
  - name: Investor Interest Signals
    description: |
      Investor interest signals: by ID and in bulk by ID.
  - name: Company Lists
    description: |
      Create, query, and maintain lists of companies, including their results.
  - name: Investor Lists
    description: |
      Create, query, and maintain lists of investors, including their results.
  - name: People Lists
    description: |
      Create, query, and maintain lists of people, including their results.
  - name: Saved Searches
    description: |
      List and delete searches saved via tryspecter.com.
  - name: Company Saved Searches
    description: |
      Details and results for saved company searches.
  - name: People Saved Searches
    description: |
      Details and results for saved people searches.
  - name: Investor Saved Searches
    description: |
      Details and results for saved investor searches.
  - name: Talent Signals Saved Searches
    description: |
      Details and results for saved Talent Signals searches.
  - name: Investor Interest Saved Searches
    description: |
      Details and results for saved Investor Interest Signals searches.
  - name: Network
    description: >
      Your team's LinkedIn network: the people and companies your teammates are
      connected to, and your reach into a given company.
  - name: Account
    description: >
      Organisation-level resources: your team's members, API call logs, and
      credit balance.
paths:
  /searches/companies/{searchId}:
    get:
      tags:
        - Company Saved Searches
      summary: Get company saved search
      description: >
        Returns count-level details for a saved company search: total companies
        matched, newly added, and companies with highlights.


        <Note> Free. This call does not consume credits. </Note>


        ## What you need


        A company saved-search ID shared with the API; get one from [Get all
        saved searches](/api-reference/saved-searches/get-all-saved-searches).


        ## Behaviour


        - Returns counts only (no per-company records); fetch the companies with
        [Get company saved search
        results](/api-reference/company-saved-searches/get-company-saved-search-results).

        - Filter the counts with `new` (companies first seen in this search),
        `newGrowthHighlights` (new growth changes), or `newFundingHighlights`
        (new funding changes).

        - The saved search must be shared with the API (via "Share to API") or
        be a global search curated by Specter.

        - `searchId` must be a number, otherwise `400`; returns `404` if the
        search doesn't exist, and `400` with `NOT_SUPPORTED_PRODUCT` if the
        search belongs to a non-company product.


        ## What you do next


        - **Pull the companies.** Fetch full records with [Get company saved
        search
        results](/api-reference/company-saved-searches/get-company-saved-search-results).
      parameters:
        - $ref: '#/components/parameters/SearchId'
        - $ref: '#/components/parameters/NewCompaniesQueryParam'
        - $ref: '#/components/parameters/NewGrowthQueryParam'
        - $ref: '#/components/parameters/NewFundingQueryParam'
      responses:
        '200':
          $ref: '#/components/responses/CompanySearchIdResponse'
        '400':
          description: BadRequest
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SearchIdBadRequest'
                  - $ref: '#/components/schemas/NotSupportedProduct'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimits'
components:
  parameters:
    SearchId:
      in: path
      name: searchId
      schema:
        type: integer
      required: true
      description: The ID of the saved search being requested.
    NewCompaniesQueryParam:
      in: query
      name: new
      schema:
        type: boolean
      required: false
      allowEmptyValue: true
      description: |
        Tells the results to have only new data since the last delivery.

        Note: Applies only to company searches
    NewGrowthQueryParam:
      in: query
      name: newGrowthHighlights
      schema:
        type: boolean
      required: false
      allowEmptyValue: true
      description: |
        Tells the results to have only companies with new growth highlights.
    NewFundingQueryParam:
      in: query
      name: newFundingHighlights
      schema:
        type: boolean
      required: false
      allowEmptyValue: true
      description: |
        Tells the results to have only companies with new funding highlights.
  responses:
    CompanySearchIdResponse:
      description: The details of the query for a given search id.
      content:
        application/json:
          schema:
            type: object
            properties:
              id:
                description: >
                  The search id for the search, this should be used to query for
                  results for the search.
                type: number
                example: 41012
              name:
                description: Name of the search
                type: string
                example: skyboundclin
              query_id:
                description: >
                  The query id that this search is related to, this can be used
                  to query for the search in the address bar.

                  `https://app.tryspecter.com/signals/company/feed?queryId=10`
                type: number
                example: 152001
              product_type:
                description: The type of product the search relates to.
                type: string
                enum:
                  - company
                  - investors
                  - people
                  - talent
                example: company
              full_count:
                description: >
                  The total number of companies that are returned by this
                  search.
                type: number
                example: 408264
              new_count:
                description: >
                  The number of new companies that have appeared in this search
                  in the most recent month.
                type: number
                example: 0
              new_funding_highlights_count:
                description: >
                  The number of companies that have new funding highlights in
                  this search.
                type: number
                example: 133
              new_growth_highlights_count:
                description: >
                  The number of companies that have new growth highlights in
                  this search.
                type: number
                example: 17988
            required:
              - id
              - name
              - product_type
              - query_id
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ApiKeyMissing'
              - $ref: '#/components/schemas/ApiKeyNotValid'
    Forbidden:
      description: Forbidden - There is no permissions to use the endpoint
      content:
        application/json:
          schema:
            type: object
            properties:
              errorCode:
                description: NOT_PERMITTED
                type: string
                example: NOT_PERMITTED
              message:
                type: string
                description: You do not have permission to access this resource.
                example: You do not have permission to access this resource.
            required:
              - errorCode
              - message
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            required:
              - errorCode
              - message
            properties:
              errorCode:
                type: string
                description: NOT_FOUND
              message:
                type: string
                description: Not Found
    RateLimits:
      description: Too Many Requests - API Rate limit exceeded
      content:
        application/json:
          schema:
            type: object
            required:
              - errorCode
              - message
            properties:
              errorCode:
                type: string
                description: RATE_LIMITED
              message:
                type: string
                description: You have been rate-limited
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
          description: The total rate limit allowed for this endpoint
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: The number of requests remaining
        X-RateLimit-Reset:
          schema:
            type: number
            format: float
          description: The number of seconds until the rate limit resets
  schemas:
    SearchIdBadRequest:
      properties:
        errorCode:
          type: string
          description: BAD_SEARCH_ID_TYPE
          example: BAD_SEARCH_ID_TYPE
        message:
          type: string
          description: The search id needs to be a number.
          example: The search id needs to be a number.
    NotSupportedProduct:
      properties:
        errorCode:
          type: string
          description: NOT_SUPPORTED_PRODUCT
          example: NOT_SUPPORTED_PRODUCT
        message:
          type: string
          description: >
            Details the product that was requested and the product that is
            supported.
          example: >
            The product "people" is not supported by this operation. Only
            "companies" are supported.
    ApiKeyMissing:
      properties:
        errorCode:
          description: API_KEY_MISSING
          example: API_KEY_MISSING
          type: string
        message:
          description: No API Key was presented on the header X-API-KEY
          example: No API Key was presented on the header X-API-KEY
          type: string
    ApiKeyNotValid:
      properties:
        errorCode:
          description: API_KEY_NOT_VALID
          example: API_KEY_NOT_VALID
          type: string
        message:
          description: API key present, but not valid
          example: API key present, but not valid
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````