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

# Count companies matching a search (free)

> Count how many companies match a plain-English sentence, a saved search or company-search filters (industry, headquarters location, headcount, revenue, funding stage, technologies, keywords). Free: no credits are charged, and no companies are listed.

Send the filter source POST /companies/search takes, exactly one of: `query`, e.g. "Series B fintech companies in New York with 50 to 200 employees"; `filters` in the POST /companies/search vocabulary; or one of your company saved searches by `savedSearchId` or `savedSearchName`. A count has no paging. Each source is resolved, refused and translated exactly as the search does it, so a count is of the companies that body would search. The answer carries `status`, `total` (the companies matching), `filters` (what was counted: send them to POST /companies/search to list the companies), `unresolvedCriteria` (parts of a `query` that could not be mapped to a filter, only with `query`) and `creditsCharged` (always 0).

The count runs in the background, usually for a few seconds: the first call answers 202 with `status` `pending`, `total` null and the `filters` being counted. Repeat the request every few seconds with those `filters` (not the `query`, which would be converted again and could count a different search) until it answers 200 with `status` `ready`. A counted search stays cached for 15 minutes, so repeating it answers at once. A count the company data provider fails or is too busy for answers 503: retry in a minute.

Only keys whose usage plan includes `company_count` may call it. Rate limit: the plan's `company_count` entry.

Errors:
- `403` `API_NOT_ON_PLAN` — The key's usage plan does not include `company_count`.
- `404` `SAVED_SEARCH_NOT_FOUND` — No saved search of yours has that id or exact title.
- `409` `SAVED_SEARCH_NAME_AMBIGUOUS` — Two of your saved searches share that title: reference it by `savedSearchId` instead.
- `422` `SAVED_SEARCH_TYPE_MISMATCH` — The saved search exists but stores the other kind of filters; `param` is `savedSearchId`.
- `422` `SAVED_SEARCH_INVALID` — The stored filters no longer form a runnable company search: the search is empty, or every value in it was retired.
- `422` `QUERY_FILTERS_INVALID` — The `query` could not be turned into filters. Name concrete criteria: industries, locations, sizes, funding stages.
- `422` `SEARCH_FILTERS_INVALID` — A filter holds a value the search cannot take; `param` names the filter and `values` the refused entry. Take values from GET /companies/filter-options.
- `422` `CITY_FILTER_UNRESOLVED` — Not one `filters.headquartersCity` name geocoded to a city, so the count was refused rather than run worldwide.
- `429` `RATE_LIMITED` — The plan's per-minute or per-day limit for `company_count` is spent.

Requires one of the following token scopes: data.



## OpenAPI

````yaml /openapi.json post /business/data/companies/count
openapi: 3.1.0
info:
  title: Fuse Business API
  version: 1.0.0
  description: >-
    External API for lists, campaigns, prospect search and contacts.
    Authenticate with your API token as HTTP Basic. All paths are under /api/v1.
servers:
  - url: https://api.tryfuse.ai/api/v1
    description: Production
security:
  - basicAuth: []
tags:
  - name: Lists
  - name: Custom columns
  - name: Smart columns
  - name: Exports
  - name: Campaigns
  - name: Knowledge hubs
  - name: Analytics
  - name: Website intent
  - name: Account
  - name: Data
  - name: Prospect search
  - name: Campaign steps
  - name: Scheduled sends
  - name: Campaign templates
  - name: Agents
  - name: Research
  - name: Company search
  - name: Saved searches
  - name: Folders
  - name: Contacts
paths:
  /business/data/companies/count:
    post:
      tags:
        - Data
      summary: Count companies matching a search (free)
      description: >-
        Count how many companies match a plain-English sentence, a saved search
        or company-search filters (industry, headquarters location, headcount,
        revenue, funding stage, technologies, keywords). Free: no credits are
        charged, and no companies are listed.


        Send the filter source POST /companies/search takes, exactly one of:
        `query`, e.g. "Series B fintech companies in New York with 50 to 200
        employees"; `filters` in the POST /companies/search vocabulary; or one
        of your company saved searches by `savedSearchId` or `savedSearchName`.
        A count has no paging. Each source is resolved, refused and translated
        exactly as the search does it, so a count is of the companies that body
        would search. The answer carries `status`, `total` (the companies
        matching), `filters` (what was counted: send them to POST
        /companies/search to list the companies), `unresolvedCriteria` (parts of
        a `query` that could not be mapped to a filter, only with `query`) and
        `creditsCharged` (always 0).


        The count runs in the background, usually for a few seconds: the first
        call answers 202 with `status` `pending`, `total` null and the `filters`
        being counted. Repeat the request every few seconds with those `filters`
        (not the `query`, which would be converted again and could count a
        different search) until it answers 200 with `status` `ready`. A counted
        search stays cached for 15 minutes, so repeating it answers at once. A
        count the company data provider fails or is too busy for answers 503:
        retry in a minute.


        Only keys whose usage plan includes `company_count` may call it. Rate
        limit: the plan's `company_count` entry.


        Errors:

        - `403` `API_NOT_ON_PLAN` — The key's usage plan does not include
        `company_count`.

        - `404` `SAVED_SEARCH_NOT_FOUND` — No saved search of yours has that id
        or exact title.

        - `409` `SAVED_SEARCH_NAME_AMBIGUOUS` — Two of your saved searches share
        that title: reference it by `savedSearchId` instead.

        - `422` `SAVED_SEARCH_TYPE_MISMATCH` — The saved search exists but
        stores the other kind of filters; `param` is `savedSearchId`.

        - `422` `SAVED_SEARCH_INVALID` — The stored filters no longer form a
        runnable company search: the search is empty, or every value in it was
        retired.

        - `422` `QUERY_FILTERS_INVALID` — The `query` could not be turned into
        filters. Name concrete criteria: industries, locations, sizes, funding
        stages.

        - `422` `SEARCH_FILTERS_INVALID` — A filter holds a value the search
        cannot take; `param` names the filter and `values` the refused entry.
        Take values from GET /companies/filter-options.

        - `422` `CITY_FILTER_UNRESOLVED` — Not one `filters.headquartersCity`
        name geocoded to a city, so the count was refused rather than run
        worldwide.

        - `429` `RATE_LIMITED` — The plan's per-minute or per-day limit for
        `company_count` is spent.


        Requires one of the following token scopes: data.
      operationId: countCompanies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filters:
                  type: object
                  properties:
                    nameLike:
                      type: array
                      items:
                        type: string
                        maxLength: 500
                      description: >-
                        Free text: company-name fragments of at most 500 chars
                        each, matched fuzzily against the company NAME only
                        (never the description). Several fragments are OR-joined
                        (provider `nameLike.anyOf`); resolve a real company to
                        its canonical name with GET
                        /companies/autocomplete?field=company.
                    domains:
                      type: array
                      items:
                        type: string
                      description: >-
                        Free text: company website domains (e.g. stripe.com). A
                        scheme, a www. prefix, a path and the letter case are
                        all stripped before the search, so
                        https://www.Stripe.com/pricing and stripe.com behave the
                        same; a value that is not a domain at all is dropped.
                        Several domains are OR-joined.
                    keywords:
                      type: array
                      items:
                        type: string
                      description: >-
                        Free-text keywords matched against company names and
                        descriptions; any may match.
                    status:
                      type: array
                      items:
                        type: object
                        properties:
                          value:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              The filter value — see the field's own description
                              for its vocabulary.
                          label:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              Display label for the value (required; repeat the
                              value when you have no label).
                          status:
                            type: string
                            enum:
                              - include
                              - exclude
                            description: >-
                              `include` matches the value; `exclude` removes
                              companies carrying it (includes OR together, every
                              exclude applies).
                        required:
                          - value
                          - label
                          - status
                      description: >-
                        Operating-status entries whose `value` is one of
                        exactly: active, acquired, closed (the `statuses` list
                        in GET /companies/filter-options). An off-list value is
                        refused with 422 SEARCH_FILTERS_INVALID, whose
                        `details.param` names this filter and `details.values`
                        the entry. Include values are OR-joined (provider
                        `anyOf`). The provider ignores an exclude list on this
                        field, so an exclusion is sent as the statuses that were
                        NOT excluded, which also drops companies whose status is
                        unknown. This filter ANDs with the others.
                    tags:
                      type: array
                      items:
                        type: object
                        properties:
                          value:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              The filter value — see the field's own description
                              for its vocabulary.
                          label:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              Display label for the value (required; repeat the
                              value when you have no label).
                          status:
                            type: string
                            enum:
                              - include
                              - exclude
                            description: >-
                              `include` matches the value; `exclude` removes
                              companies carrying it (includes OR together, every
                              exclude applies).
                        required:
                          - value
                          - label
                          - status
                      description: >-
                        Company-tag entries whose `value` is a slug from
                        `companyTags` in GET /companies/filter-options:
                        raised-from-top-vc, venture-backed-startup,
                        is-government, is-school. An off-list value is refused
                        with 422 SEARCH_FILTERS_INVALID, whose `details.param`
                        names this filter and `details.values` the entry.
                        Include values are OR-joined (provider `anyOf`) and
                        every exclude value is removed (`noneOf`); this filter
                        ANDs with the others.
                    industriesV2:
                      type: array
                      items:
                        type: object
                        properties:
                          value:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              The filter value — see the field's own description
                              for its vocabulary.
                          label:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              Display label for the value (required; repeat the
                              value when you have no label).
                          status:
                            type: string
                            enum:
                              - include
                              - exclude
                            description: >-
                              `include` matches the value; `exclude` removes
                              companies carrying it (includes OR together, every
                              exclude applies).
                        required:
                          - value
                          - label
                          - status
                      description: >-
                        Industry entries whose `value` is one of the
                        `fiberIndustries` values in GET
                        /companies/filter-options, copied exactly as listed
                        (e.g. Software, Finance). An off-list value is refused
                        with 422 SEARCH_FILTERS_INVALID, whose `details.param`
                        names this filter and `details.values` the entry.
                        Include values are OR-joined (provider `anyOf`) and
                        every exclude value is removed (`noneOf`); this filter
                        ANDs with the others.
                    linkedinIndustries:
                      type: array
                      items:
                        type: object
                        properties:
                          value:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              The filter value — see the field's own description
                              for its vocabulary.
                          label:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              Display label for the value (required; repeat the
                              value when you have no label).
                          status:
                            type: string
                            enum:
                              - include
                              - exclude
                            description: >-
                              `include` matches the value; `exclude` removes
                              companies carrying it (includes OR together, every
                              exclude applies).
                        required:
                          - value
                          - label
                          - status
                      description: >-
                        LinkedIn-industry entries whose `value` is one of the
                        `linkedinIndustries` values in GET
                        /companies/filter-options, copied exactly as listed
                        (e.g. Software Development) — a much finer taxonomy than
                        `industriesV2`. An off-list value is not rejected: the
                        search comes back empty with no error naming the field,
                        so check the value against the list first. Include
                        values are OR-joined (provider `anyOf`) and every
                        exclude value is removed (`noneOf`); this filter ANDs
                        with the others.
                    crunchbaseCategories:
                      type: array
                      items:
                        type: object
                        properties:
                          value:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              The filter value — see the field's own description
                              for its vocabulary.
                          label:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              Display label for the value (required; repeat the
                              value when you have no label).
                          status:
                            type: string
                            enum:
                              - include
                              - exclude
                            description: >-
                              `include` matches the value; `exclude` removes
                              companies carrying it (includes OR together, every
                              exclude applies).
                        required:
                          - value
                          - label
                          - status
                      description: >-
                        Crunchbase-category entries whose `value` is one of the
                        `crunchbaseIndustries` values in GET
                        /companies/filter-options, copied exactly as listed
                        (e.g. Financial Services). An off-list value is not
                        rejected: the search comes back empty with no error
                        naming the field, so check the value against the list
                        first. Include values are OR-joined (provider `anyOf`)
                        and every exclude value is removed (`noneOf`); this
                        filter ANDs with the others.
                    crunchbaseCategoryGroups:
                      type: array
                      items:
                        type: string
                      description: >-
                        Crunchbase category groups as plain strings copied
                        verbatim (case-sensitive) from
                        `crunchbaseCategoryGroups` in GET
                        /companies/filter-options (e.g. Financial Services) —
                        the broad parent of `crunchbaseCategories`. An off-list
                        value is not rejected: the search comes back empty with
                        no error naming the field, so check the value against
                        the list first. Several groups are OR-joined (provider
                        `anyOf`); this filter has no exclude form.
                    naicsCodes:
                      type: array
                      items:
                        type: object
                        properties:
                          value:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              The filter value — see the field's own description
                              for its vocabulary.
                          label:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              Display label for the value (required; repeat the
                              value when you have no label).
                          status:
                            type: string
                            enum:
                              - include
                              - exclude
                            description: >-
                              `include` matches the value; `exclude` removes
                              companies carrying it (includes OR together, every
                              exclude applies).
                        required:
                          - value
                          - label
                          - status
                      description: >-
                        NAICS entries whose `value` is the code, not the title
                        (`naicsCodes[].code` in GET /companies/filter-options,
                        e.g. 513210 for Software Publishers; 2- to 6-digit codes
                        are all accepted, a shorter code being the broader
                        sector). An off-list value is not rejected: the search
                        comes back empty with no error naming the field, so
                        check the value against the list first. Include values
                        are OR-joined (provider `anyOf`) and every exclude value
                        is removed (`noneOf`); this filter ANDs with the others.
                    headquartersCountryCode:
                      type: array
                      items:
                        type: object
                        properties:
                          value:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              The filter value — see the field's own description
                              for its vocabulary.
                          label:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              Display label for the value (required; repeat the
                              value when you have no label).
                          status:
                            type: string
                            enum:
                              - include
                              - exclude
                            description: >-
                              `include` matches the value; `exclude` removes
                              companies carrying it (includes OR together, every
                              exclude applies).
                        required:
                          - value
                          - label
                          - status
                      description: >-
                        Headquarters-country entries whose `value` is the
                        country's three-letter `apiCode` from `countries` in GET
                        /companies/filter-options (e.g. USA, DEU). The
                        two-letter `isoCodeAlpha2` in the same row (US, DE) is
                        also accepted and converted to the `apiCode`. Any other
                        value is refused with 422 SEARCH_FILTERS_INVALID, whose
                        `details.param` names this filter and `details.values`
                        the entry. Include values are OR-joined (provider
                        `anyOf`) and every exclude value is removed (`noneOf`);
                        this filter ANDs with the others.
                    headquartersStateName:
                      type: array
                      items:
                        type: object
                        properties:
                          value:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              The filter value — see the field's own description
                              for its vocabulary.
                          label:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              Display label for the value (required; repeat the
                              value when you have no label).
                          status:
                            type: string
                            enum:
                              - include
                              - exclude
                            description: >-
                              `include` matches the value; `exclude` removes
                              companies carrying it (includes OR together, every
                              exclude applies).
                        required:
                          - value
                          - label
                          - status
                      description: >-
                        Headquarters state/province entries whose `value` is the
                        full state or province name (e.g. Florida, California).
                    headquartersCity:
                      type: array
                      items:
                        type: string
                        minLength: 1
                        maxLength: 200
                      maxItems: 25
                      description: >-
                        Up to 25 fully qualified place names from GET
                        /companies/autocomplete?field=location (e.g. Dallas,
                        Texas, United States); each is geocoded independently to
                        its city bounds and the areas are OR-ed together (no
                        exclusion). A name that geocodes to nothing is dropped
                        and the search runs on the names that did resolve — take
                        the values from the typeahead so every one of them
                        counts — and only when NOT ONE of them resolves is the
                        search refused rather than run worldwide (422
                        CITY_FILTER_UNRESOLVED).
                    employeeCountV2:
                      type: object
                      properties:
                        min:
                          type: number
                          description: >-
                            Lower bound, inclusive — except on
                            `employeeCountV2`, whose lower bound is exclusive
                            (see that field). 0 or less is no bound.
                        max:
                          type: number
                          description: Inclusive upper bound; 0 or less is no bound.
                      description: >-
                        Headcount range `{ min?, max? }`; any whole number is
                        taken on either side and is used as sent — the values
                        the search UI offers (1, 10, 50, 200, 500, 1000, 5000,
                        10000) are its own vocabulary, not a constraint here.
                        The lower bound is EXCLUSIVE and the upper bound
                        inclusive, so `{ min: 50 }` matches companies with MORE
                        than 50 employees, and `{ min: 300, max: 320 }` matches
                        301 to 320. Inverted bounds are read the other way
                        round, and an equal pair keeps only the lower bound,
                        because the provider rejects a range whose bounds meet.
                    revenueUSD:
                      type: object
                      properties:
                        min:
                          type: number
                          description: >-
                            Lower bound, inclusive — except on
                            `employeeCountV2`, whose lower bound is exclusive
                            (see that field). 0 or less is no bound.
                        max:
                          type: number
                          description: Inclusive upper bound; 0 or less is no bound.
                      description: >-
                        Estimated annual revenue range `{ min?, max? }`; the
                        accepted values are whole US dollars, not millions
                        (5000000 means $5M), and both bounds are inclusive.
                    totalFundingUSD:
                      type: object
                      properties:
                        min:
                          type: number
                          description: >-
                            Lower bound, inclusive — except on
                            `employeeCountV2`, whose lower bound is exclusive
                            (see that field). 0 or less is no bound.
                        max:
                          type: number
                          description: Inclusive upper bound; 0 or less is no bound.
                      description: >-
                        Total funding raised range `{ min?, max? }`; the
                        accepted values are whole US dollars, not millions
                        (5000000 means $5M), and both bounds are inclusive.
                    lastFundingUSD:
                      type: object
                      properties:
                        min:
                          type: number
                          description: >-
                            Lower bound, inclusive — except on
                            `employeeCountV2`, whose lower bound is exclusive
                            (see that field). 0 or less is no bound.
                        max:
                          type: number
                          description: Inclusive upper bound; 0 or less is no bound.
                      description: >-
                        Size range of the most recent funding round `{ min?,
                        max? }`; the accepted values are whole US dollars, not
                        millions (5000000 means $5M), and both bounds are
                        inclusive.
                    stage:
                      type: array
                      items:
                        type: object
                        properties:
                          value:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              The filter value — see the field's own description
                              for its vocabulary.
                          label:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              Display label for the value (required; repeat the
                              value when you have no label).
                          status:
                            type: string
                            enum:
                              - include
                              - exclude
                            description: >-
                              `include` matches the value; `exclude` removes
                              companies carrying it (includes OR together, every
                              exclude applies).
                        required:
                          - value
                          - label
                          - status
                      description: >-
                        Funding-stage entries whose `value` is one of exactly:
                        pre_seed, seed, series_a, series_b, series_c, series_d,
                        series_e, series_f, series_g, series_h, series_i,
                        series_j, public, acquired, closed, private_equity,
                        venture_other, no_funding_yet, unknown (the
                        `fundingStages` list in GET /companies/filter-options).
                        An off-list value is refused with 422
                        SEARCH_FILTERS_INVALID, whose `details.param` names this
                        filter and `details.values` the entry. Include values
                        are OR-joined (provider `anyOf`) and every exclude value
                        is removed (`noneOf`); this filter ANDs with the others.
                    technologies:
                      type: array
                      items:
                        type: object
                        properties:
                          value:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              The filter value — see the field's own description
                              for its vocabulary.
                          label:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              Display label for the value (required; repeat the
                              value when you have no label).
                          status:
                            type: string
                            enum:
                              - include
                              - exclude
                            description: >-
                              `include` matches the value; `exclude` removes
                              companies carrying it (includes OR together, every
                              exclude applies).
                        required:
                          - value
                          - label
                          - status
                      description: >-
                        Technology-in-use entries whose `value` is a name from
                        the provider's predefined technology vocabulary,
                        forwarded verbatim, so it must carry the product's own
                        spelling and casing — e.g. Salesforce, Kubernetes,
                        Next.js, Google Analytics, and `AWS` for Amazon Web
                        Services. No endpoint serves this vocabulary yet; the
                        product's own picker offers a curated 141-name subset.
                        An off-list value is refused with 422
                        SEARCH_FILTERS_INVALID, whose `details.param` names this
                        filter and `details.values` the entry. Include values
                        are OR-joined (provider `anyOf`) and every exclude value
                        is removed (`noneOf`); this filter ANDs with the others.
                    investors:
                      type: array
                      items:
                        type: object
                        properties:
                          value:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              The filter value — see the field's own description
                              for its vocabulary.
                          label:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              Display label for the value (required; repeat the
                              value when you have no label).
                          status:
                            type: string
                            enum:
                              - include
                              - exclude
                            description: >-
                              `include` matches the value; `exclude` removes
                              companies carrying it (includes OR together, every
                              exclude applies).
                        required:
                          - value
                          - label
                          - status
                      description: >-
                        Investor entries whose `value` is the investor's website
                        domain — resolve names with GET
                        /companies/autocomplete?field=company&orgType=investor
                        and send the `domain` from that response, never the
                        investor's name. An off-list value is not rejected: the
                        search comes back empty with no error naming the field,
                        so check the value against the list first. Include
                        values are OR-joined (provider `anyOf`) and every
                        exclude value is removed (`noneOf`); this filter ANDs
                        with the others.
                    foundedOn:
                      type: object
                      properties:
                        start:
                          type: string
                          description: Earliest date, ISO-8601 (e.g. 2020-01-01).
                        end:
                          type: string
                          description: Latest date, ISO-8601 (e.g. 2024-12-31).
                      description: >-
                        Founding-date range `{ start?, end? }` as ISO-8601
                        dates.
                    lastFundedOn:
                      type: object
                      properties:
                        start:
                          type: string
                          description: Earliest date, ISO-8601 (e.g. 2020-01-01).
                        end:
                          type: string
                          description: Latest date, ISO-8601 (e.g. 2024-12-31).
                      description: >-
                        Date range of the most recent funding round, `{ start?,
                        end? }` as ISO-8601 dates.
                    acceleratorsV2:
                      type: array
                      items:
                        type: object
                        properties:
                          value:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              The filter value — see the field's own description
                              for its vocabulary.
                          label:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              Display label for the value (required; repeat the
                              value when you have no label).
                          status:
                            type: string
                            enum:
                              - include
                              - exclude
                            description: >-
                              `include` matches the value; `exclude` removes
                              companies carrying it (includes OR together, every
                              exclude applies).
                        required:
                          - value
                          - label
                          - status
                      description: >-
                        Accelerator entries whose `value` is the
                        `acceleratorSlug` from `accelerators` in GET
                        /companies/filter-options (e.g. ycombinator, techstars);
                        the `acceleratorName` in the same row is NOT accepted.
                        An off-list value is refused with 422
                        SEARCH_FILTERS_INVALID, whose `details.param` names this
                        filter and `details.values` the entry. Include values
                        are OR-joined (provider `anyOf`) and every exclude value
                        is removed (`noneOf`); this filter ANDs with the others.
                    fortuneRankings:
                      type: array
                      items:
                        type: object
                        properties:
                          value:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              The filter value — see the field's own description
                              for its vocabulary.
                          label:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              Display label for the value (required; repeat the
                              value when you have no label).
                          status:
                            type: string
                            enum:
                              - include
                              - exclude
                            description: >-
                              `include` matches the value; `exclude` removes
                              companies carrying it (includes OR together, every
                              exclude applies).
                        required:
                          - value
                          - label
                          - status
                      description: >-
                        Ranking-list entries whose `value` is one of exactly:
                        fortune-500, fortune-1000, forbes-global-2000 (the
                        `fortuneRankings` list in GET /companies/filter-options;
                        fortune-1000 contains fortune-500). Any other value is
                        refused with 422 SEARCH_FILTERS_INVALID, whose
                        `details.param` names this filter and `details.values`
                        the entry. Include values are OR-joined (provider
                        `anyOf`). The provider takes an include list only here,
                        and the tiers nest, so an exclude value cannot be
                        honoured and is ignored. This filter ANDs with the
                        others.
                    officeLocationsV2:
                      type: array
                      items:
                        type: object
                        properties:
                          value:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              The filter value — see the field's own description
                              for its vocabulary.
                          label:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: >-
                              Display label for the value (required; repeat the
                              value when you have no label).
                          status:
                            type: string
                            enum:
                              - include
                              - exclude
                            description: >-
                              `include` matches the value; `exclude` removes
                              companies carrying it (includes OR together, every
                              exclude applies).
                        required:
                          - value
                          - label
                          - status
                      description: >-
                        Office-location entries whose `value` is a country's
                        three-letter `apiCode` from `countries` in GET
                        /companies/filter-options (e.g. USA) — the same
                        vocabulary as `headquartersCountryCode`, but matching
                        ANY office rather than only the headquarters. The
                        two-letter `isoCodeAlpha2` (US) is also accepted and
                        converted to the `apiCode`. Any other value is refused
                        with 422 SEARCH_FILTERS_INVALID, whose `details.param`
                        names this filter and `details.values` the entry.
                        Include values are OR-joined (provider `anyOf`) and
                        every exclude value is removed (`noneOf`); this filter
                        ANDs with the others.
                    linkedinSlugs:
                      type: array
                      items:
                        type: string
                      description: >-
                        Free text: LinkedIn company slugs (e.g. stripe). A full
                        company URL is accepted and reduced to the part after
                        linkedin.com/company/, and the value is lower-cased,
                        because the provider matches the slug exactly. Several
                        slugs are OR-joined.
                  description: >-
                    Literal filters, one of the four filter sources. Company
                    filters in the search vocabulary: include/exclude fields
                    take `[{ status, value, label }]` entries (`label` is
                    required), list fields arrays of strings, ranges `{ min, max
                    }` and date ranges `{ start, end }` — enum vocabularies come
                    from GET /companies/filter-options, names and places from
                    GET /companies/autocomplete. Must contain at least one
                    non-empty value.
                savedSearchId:
                  type: string
                  description: >-
                    Id of one of your COMPANY saved searches to take the filters
                    from instead of `filters` (a people saved search answers 422
                    SAVED_SEARCH_TYPE_MISMATCH).
                savedSearchName:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: >-
                    Exact title of one of your company saved searches to take
                    the filters from instead of `filters`; two searches sharing
                    the title answer 409 SAVED_SEARCH_NAME_AMBIGUOUS.
                query:
                  type: string
                  minLength: 1
                  maxLength: 2000
                  description: >-
                    Natural-language description of the companies to find (max
                    2000 chars), converted into filters server-side instead of
                    `filters`; criteria that could not be mapped come back as
                    `unresolvedCriteria`, and a query yielding no filter answers
                    422 QUERY_FILTERS_INVALID.
              description: >-
                Exactly one filter source, as POST /companies/search takes it:
                `filters`, `savedSearchId`, `savedSearchName` or `query`. A
                count has no paging.
      responses:
        '200':
          description: Success
          headers:
            RateLimit-Limit:
              schema:
                type: integer
              description: Requests permitted in the current window.
            RateLimit-Remaining:
              schema:
                type: integer
              description: Requests remaining in the current window.
            RateLimit-Reset:
              schema:
                type: integer
              description: Seconds until the current window resets.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - total
                  - filters
                  - creditsCharged
                properties:
                  status:
                    type: string
                    enum:
                      - ready
                      - pending
                    description: >-
                      `ready` (200) with the `total`, or `pending` (202) while
                      the count runs: repeat the request.
                  total:
                    type:
                      - integer
                      - 'null'
                    description: Companies matching the filters; null while `pending`.
                  filters:
                    type: object
                    additionalProperties: true
                    description: >-
                      The filters counted, in the POST /companies/search
                      vocabulary.
                  unresolvedCriteria:
                    type: array
                    items:
                      type: string
                    description: >-
                      Only with `query`: the parts of the sentence no filter
                      could express.
                  creditsCharged:
                    type: integer
                    description: 'Always 0: counting is free.'
              example:
                status: ready
                total: 1287
                filters:
                  crunchbaseCategoryGroups:
                    - Financial Services
                  stage:
                    - label: Series B
                      value: series_b
                      status: include
                  headquartersCity:
                    - New York
                  employeeCountV2:
                    min: 50
                    max: 200
                unresolvedCriteria: []
                creditsCharged: 0
        '202':
          description: >-
            The count is still running: repeat the request with the returned
            `filters` until it answers 200.
          headers:
            RateLimit-Limit:
              schema:
                type: integer
              description: Requests permitted in the current window.
            RateLimit-Remaining:
              schema:
                type: integer
              description: Requests remaining in the current window.
            RateLimit-Reset:
              schema:
                type: integer
              description: Seconds until the current window resets.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  total:
                    type:
                      - string
                      - 'null'
                  filters:
                    type: object
                    properties:
                      crunchbaseCategoryGroups:
                        type: array
                        items:
                          type: string
                      stage:
                        type: array
                        items:
                          type: object
                          properties:
                            label:
                              type: string
                            value:
                              type: string
                            status:
                              type: string
                      headquartersCity:
                        type: array
                        items:
                          type: string
                      employeeCountV2:
                        type: object
                        properties:
                          min:
                            type: integer
                          max:
                            type: integer
                  unresolvedCriteria:
                    type: array
                    items: {}
                  creditsCharged:
                    type: integer
              example:
                status: pending
                total: null
                filters:
                  crunchbaseCategoryGroups:
                    - Financial Services
                  stage:
                    - label: Series B
                      value: series_b
                      status: include
                  headquartersCity:
                    - New York
                  employeeCountV2:
                    min: 50
                    max: 200
                unresolvedCriteria: []
                creditsCharged: 0
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - basicAuth: []
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            param:
              type:
                - string
                - 'null'
            doc_url:
              type:
                - string
                - 'null'
            request_id:
              type:
                - string
                - 'null'
          required:
            - code
            - message
      required:
        - error
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Your API token (`af_…`) as the Basic-auth username, with an empty
        password.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.