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

# Company Search Count API

> Count the companies a company search would match, free and without returning records, to size a list before you buy it.

Send what [Company Search](https://www.datalegion.ai/docs/api-reference/company-search.md) takes (`filters`, `sql` or `es_query`) and get back how many companies it matches, rounded, without any records. A count costs no credits, so you can size a list and work out what it would cost (one credit per record returned) before you search.

```json theme={"dark"}
{ "filters": { "industry": "software development", "locations.city": "austin" } }
```

```json theme={"dark"}
{ "total": 1200, "total_status": "about" }
```

## Reading the Total

`total` is rounded, and `total_status` (also the `Total-Count-Status` response header) says how to read it:

| total\_status | Meaning | Say it as |
| - | - | - |
| `about` | The count, rounded: to the nearest 10 under 100, else to two significant figures | "about 1,200" |
| `at_least` | Counting ran out of time on a very broad search; `total` is a lower bound | "1,200 or more" |
| `under` | Fewer than 10 match, possibly none | "fewer than 10" |

A count is rounded, so adding or removing one record almost never changes it. For an exact total, run the search itself: its `total` is exact for selective queries.

A count describes a list, not one record: it refuses (400, free) filters on fields that identify a single company: `legion_id`, its name, domain, LinkedIn URL and ticker. Whether a field is filled is fine, for example "public companies with a ticker": `"tickers.symbol": {"exists": true}`; only a specific value is refused. To look one up, use [Company Enrichment](https://www.datalegion.ai/docs/api-reference/company-enrichment.md).

Sent as `filters`, the response also carries `generated_query`, the query object the filters compiled to.

## Limits

* Free: no credits are used.
* Works with zero credits left: a count needs an active plan that includes search (a trial counts too), not a balance, so you can size a list before you buy more. An expired plan answers 402; a plan without search, 403.
* 10 counts a minute and 100 an hour per account (5 and 30 on a free trial), for each of person and company. Higher limits are available on request.
* The same field rules as search: a filter on a field outside your plan is refused, and opted-out records are never counted.
* GET works too, with `filters`, `sql` or `es_query` as query parameters (`filters` and `es_query` as JSON text). Prefer POST.


## OpenAPI

````yaml POST /company/search/count
openapi: 3.1.0
info:
  title: Data Legion API
  description: API for enriching, searching, and discovering person and company data
  version: 1.0.0
servers:
  - url: https://api.datalegion.ai
security:
  - APIKeyHeader: []
paths:
  /company/search/count:
    post:
      tags:
        - company
        - company
        - search
      summary: Count companies a search would match
      description: >-
        How many companies a search query matches, rounded, without returning
        records. Free: no credits used. Takes what search takes (SQL, a query
        object or filters) and applies the same field and plan rules. Totals are
        rounded (to the nearest 10 under 100, else to two significant figures)
        and fewer than 10 reads as under 10.
      operationId: count_companies_company_search_count_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyCountRequest'
      responses:
        '200':
          description: Success - the rounded count of matching companies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountResponse'
        '400':
          description: Bad request - invalid query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            Forbidden - no search contract, or the query names a field outside
            it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '408':
          description: Request timeout - query exceeded the execution time limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error - invalid field format or value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests - per-minute or hourly count limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CompanyCountRequest:
      additionalProperties: false
      description: Request model for a company search's count.
      example:
        filters:
          industries:
            - software development
          sizes:
            - 51-200
      properties:
        query:
          anyOf:
            - type: string
            - additionalProperties: true
              type: object
            - type: 'null'
          default: null
          deprecated: true
          description: >-
            Deprecated: send sql or es_query. A SQL SELECT statement when text,
            a query object when an object (or text starting with "{"); still
            accepted as before.
          title: Query
        sql:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            A SQL SELECT statement (no LIMIT or OFFSET clause: use limit and
            offset).
          title: Sql
        es_query:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          default: null
          description: >-
            A query object in the Elasticsearch query DSL, naming the response's
            field paths (bool, term, terms, match, match_phrase, range, exists,
            prefix, wildcard, nested). A GET may send it as JSON text.
          title: Es Query
        pretty_print:
          type: boolean
          title: Pretty Print
          description: If true, pretty-print JSON response with indentation.
          default: false
        filters:
          anyOf:
            - $ref: '#/components/schemas/CompanyFilters'
            - $ref: '#/components/schemas/CompanyFilterGroup'
            - type: 'null'
          default: null
          description: >-
            Filters on the record's own field names (job_title, state_code,
            company_industry, locations.city, ...): a value or a list (any of),
            {"gte"/"lte"} for a range, {"exists": true}, true/false for a flag.
            Every field given must hold; group sets with {"and": [...]}, {"or":
            [...]} or {"not": {...}}; keywords takes a Boolean search string.
            The response's generated_query is the query object they compiled to.
          title: Filters
      title: CompanyCountRequest
      type: object
    CountResponse:
      description: How many records a search would match, rounded.
      properties:
        total:
          description: >-
            How many records the query matches, rounded: to the nearest 10 under
            100, else to two significant figures. Read it with total_status.
          title: Total
          type: integer
        total_status:
          description: >-
            `about`: total is the rounded count. `at_least`: counting ran out of
            time, so total is a lower bound. `under`: fewer than total (10)
            match, possibly none.
          enum:
            - about
            - at_least
            - under
          title: Total Status
          type: string
        generated_query:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          default: null
          description: >-
            Present when the search was sent as filters: the query object they
            compiled to, which es_query takes as is.
          title: Generated Query
      required:
        - total
        - total_status
      title: CountResponse
      type: object
    ErrorResponse:
      properties:
        error:
          type: string
          title: Error
          description: Error type/code
        message:
          type: string
          title: Message
          description: Human-readable error message
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - items: {}
              type: array
            - type: 'null'
          title: Details
          description: Additional error details (for validation errors)
      type: object
      required:
        - error
        - message
      title: ErrorResponse
      description: Error response model for customer-facing API.
    CompanyFilters:
      additionalProperties: false
      description: The company record's own field names; every one given must hold.
      minProperties: 1
      properties:
        build_version:
          $ref: '#/components/schemas/FilterValue'
        description.cleaned:
          $ref: '#/components/schemas/FilterValue'
        description.raw:
          $ref: '#/components/schemas/FilterValue'
        domain:
          $ref: '#/components/schemas/FilterValue'
        domains.domain:
          $ref: '#/components/schemas/FilterValue'
        founded:
          $ref: '#/components/schemas/FilterValue'
        headline.cleaned:
          $ref: '#/components/schemas/FilterValue'
        headline.raw:
          $ref: '#/components/schemas/FilterValue'
        industry:
          $ref: '#/components/schemas/FilterValue'
        keywords:
          description: >-
            Boolean search over the profile text: words and "quoted phrases",
            AND, OR, NOT in capitals, parentheses.
          type: string
        last_seen:
          $ref: '#/components/schemas/FilterValue'
        legion_attrition_count.12m:
          $ref: '#/components/schemas/FilterValue'
        legion_attrition_count.1m:
          $ref: '#/components/schemas/FilterValue'
        legion_attrition_count.3m:
          $ref: '#/components/schemas/FilterValue'
        legion_attrition_count.6m:
          $ref: '#/components/schemas/FilterValue'
        legion_average_tenure:
          $ref: '#/components/schemas/FilterValue'
        legion_education_distribution:
          $ref: '#/components/schemas/FilterValue'
        legion_employee_count:
          $ref: '#/components/schemas/FilterValue'
        legion_employee_count_by_month.count:
          $ref: '#/components/schemas/FilterValue'
        legion_employee_count_by_month.departures:
          $ref: '#/components/schemas/FilterValue'
        legion_employee_count_by_month.growth_rate:
          $ref: '#/components/schemas/FilterValue'
        legion_employee_count_by_month.hires:
          $ref: '#/components/schemas/FilterValue'
        legion_employee_count_by_month.month:
          $ref: '#/components/schemas/FilterValue'
        legion_employee_count_by_month.net_change:
          $ref: '#/components/schemas/FilterValue'
        legion_employee_growth_rate.12m:
          $ref: '#/components/schemas/FilterValue'
        legion_employee_growth_rate.1m:
          $ref: '#/components/schemas/FilterValue'
        legion_employee_growth_rate.3m:
          $ref: '#/components/schemas/FilterValue'
        legion_employee_growth_rate.6m:
          $ref: '#/components/schemas/FilterValue'
        legion_expense_category_distribution:
          $ref: '#/components/schemas/FilterValue'
        legion_expense_category_growth_rate:
          $ref: '#/components/schemas/FilterValue'
        legion_id:
          $ref: '#/components/schemas/FilterValue'
        legion_job_function_distribution:
          $ref: '#/components/schemas/FilterValue'
        legion_job_function_growth_rate:
          $ref: '#/components/schemas/FilterValue'
        legion_new_hire_count.12m:
          $ref: '#/components/schemas/FilterValue'
        legion_new_hire_count.1m:
          $ref: '#/components/schemas/FilterValue'
        legion_new_hire_count.3m:
          $ref: '#/components/schemas/FilterValue'
        legion_new_hire_count.6m:
          $ref: '#/components/schemas/FilterValue'
        legion_seniority_distribution:
          $ref: '#/components/schemas/FilterValue'
        legion_seniority_growth_rate:
          $ref: '#/components/schemas/FilterValue'
        legion_tenure_distribution:
          $ref: '#/components/schemas/FilterValue'
        legion_turnover_rate.12m:
          $ref: '#/components/schemas/FilterValue'
        legion_turnover_rate.1m:
          $ref: '#/components/schemas/FilterValue'
        legion_turnover_rate.3m:
          $ref: '#/components/schemas/FilterValue'
        legion_turnover_rate.6m:
          $ref: '#/components/schemas/FilterValue'
        linkedin_employee_count:
          $ref: '#/components/schemas/FilterValue'
        linkedin_followers:
          $ref: '#/components/schemas/FilterValue'
        linkedin_id:
          $ref: '#/components/schemas/FilterValue'
        linkedin_url:
          $ref: '#/components/schemas/FilterValue'
        locations.address_line_2:
          $ref: '#/components/schemas/FilterValue'
        locations.city:
          $ref: '#/components/schemas/FilterValue'
        locations.continent:
          $ref: '#/components/schemas/FilterValue'
        locations.continent_code:
          $ref: '#/components/schemas/FilterValue'
        locations.country:
          $ref: '#/components/schemas/FilterValue'
        locations.country_code:
          $ref: '#/components/schemas/FilterValue'
        locations.current:
          $ref: '#/components/schemas/FilterValue'
        locations.geo:
          $ref: '#/components/schemas/FilterValue'
        locations.last_seen:
          $ref: '#/components/schemas/FilterValue'
        locations.num_sources:
          $ref: '#/components/schemas/FilterValue'
        locations.postal_code:
          $ref: '#/components/schemas/FilterValue'
        locations.primary:
          $ref: '#/components/schemas/FilterValue'
        locations.raw:
          $ref: '#/components/schemas/FilterValue'
        locations.state:
          $ref: '#/components/schemas/FilterValue'
        locations.state_code:
          $ref: '#/components/schemas/FilterValue'
        locations.street_address:
          $ref: '#/components/schemas/FilterValue'
        name.cleaned:
          $ref: '#/components/schemas/FilterValue'
        name.display:
          $ref: '#/components/schemas/FilterValue'
        name.raw:
          $ref: '#/components/schemas/FilterValue'
        num_sources:
          $ref: '#/components/schemas/FilterValue'
        size:
          $ref: '#/components/schemas/FilterValue'
        socials.id:
          $ref: '#/components/schemas/FilterValue'
        socials.network:
          $ref: '#/components/schemas/FilterValue'
        socials.url:
          $ref: '#/components/schemas/FilterValue'
        socials.username:
          $ref: '#/components/schemas/FilterValue'
        tickers.exchange:
          $ref: '#/components/schemas/FilterValue'
        tickers.symbol:
          $ref: '#/components/schemas/FilterValue'
        type:
          $ref: '#/components/schemas/FilterValue'
      type: object
    CompanyFilterGroup:
      additionalProperties: false
      description: 'and: all hold; or: any holds; not: it doesn''t. Up to 3 levels.'
      maxProperties: 1
      minProperties: 1
      properties:
        and:
          items:
            anyOf:
              - $ref: '#/components/schemas/CompanyFilters'
              - $ref: '#/components/schemas/CompanyFilterGroup'
          maxItems: 20
          minItems: 1
          type: array
        not:
          anyOf:
            - $ref: '#/components/schemas/CompanyFilters'
            - $ref: '#/components/schemas/CompanyFilterGroup'
        or:
          items:
            anyOf:
              - $ref: '#/components/schemas/CompanyFilters'
              - $ref: '#/components/schemas/CompanyFilterGroup'
          maxItems: 20
          minItems: 1
          type: array
      type: object
    FilterValue:
      anyOf:
        - type:
            - string
            - number
            - boolean
        - items:
            type:
              - string
              - number
              - boolean
          maxItems: 100
          minItems: 1
          type: array
        - additionalProperties: false
          minProperties: 1
          properties:
            gt:
              type:
                - number
                - string
            gte:
              type:
                - number
                - string
            lt:
              type:
                - number
                - string
            lte:
              type:
                - number
                - string
          type: object
        - additionalProperties: false
          properties:
            exists:
              type: boolean
          required:
            - exists
          type: object
      description: >-
        A value, or a list of values (any of them); {"gte", "gt", "lte", "lt"}
        for a range; {"exists": true|false} for whether it holds a value.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: API-Key

````

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