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

# Count matching lawsuits

> Counts how many lawsuits match the filter, excluding those your company has already retrieved. Free and synchronous — use it before creating a paid query.



## OpenAPI

````yaml openapi/miner.yaml POST /requests/count
openapi: 3.0.3
info:
  title: Judit Miner API — Requests, responses & tribunals
  description: >
    OpenAPI description for miner API routes that manage lawsuit search
    **requests**

    (count, create, status), paginated **responses** (lawsuit results), and the

    **tribunals** reference list (ids used in request filters).


    - `company_id` and `user_id` are **not** sent by the client on `POST
    /requests/create`;
      the server fills them from the authenticated session.
    - On `POST /requests/count`, the server merges `company_id` and `user_id`
    from context
      first; clients should send only filter fields (see request body schema).
    - Request and response bodies use **JSON**. Date-time fields are ISO 8601
    strings.

    - Count/create bodies are validated with a **strict** object (unknown keys
    are rejected).


    Authentication and `miner_enabled` behavior are enforced by
    `@judit-io/server`

    (e.g. JWT / gateway); this spec requires an API key provided in the
    `api-key` header.
  version: 1.0.0
servers:
  - url: https://miner.production.judit.io
    description: Production server
security:
  - ApiKeyAuth: []
tags:
  - name: Requests
    description: Create and inspect lawsuit search requests
  - name: Responses
    description: Paginated lawsuit results for a completed find request
  - name: Tribunals
    description: Reference data for tribunal identifiers used in filters
paths:
  /requests/count:
    post:
      tags:
        - Requests
      summary: Count matching lawsuits and record a count request
      description: >
        Runs a lawsuit count with the given filters (excluding lawsuits that
        already

        have a response for the company), persists a **count**-type request in
        **completed**

        status, and returns the total and new `request_id`.


        Returns **201 Created** on success.
      operationId: postRequestsCount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestLawsuitsFiltersBody'
            examples:
              judgementBond:
                summary: Judgement bond with tribunals
                value:
                  kind: judgement-bond
                  tribunals:
                    - 1
                    - 2
                  budget_years:
                    - 2024
                  natures:
                    - common
      responses:
        '201':
          description: Count stored; response includes totals and optional echo of filters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountRequestSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  schemas:
    RequestLawsuitsFiltersBody:
      type: object
      additionalProperties: false
      required:
        - kind
      properties:
        kind:
          $ref: '#/components/schemas/LawsuitKind'
        amount_min:
          type: number
          description: >-
            Minimum lawsuit amount filter (cannot be combined with
            `amount_tier`)
        amount_max:
          type: number
          description: >-
            Maximum lawsuit amount filter (cannot be combined with
            `amount_tier`)
        amount_tier:
          $ref: '#/components/schemas/AmountTier'
        tribunals:
          type: array
          items:
            type: integer
        budget_years:
          type: array
          items:
            type: integer
          description: Only when `kind` is `judgement-bond`
        natures:
          type: array
          items:
            $ref: '#/components/schemas/LawsuitNature'
          description: Only when `kind` is `judgement-bond`
        tags:
          type: array
          items:
            $ref: '#/components/schemas/LawsuitTag'
          description: Only when `kind` is `sentence-execution`
        responses_limit:
          type: integer
          minimum: 1
          description: >
            Caps how many lawsuits are included in a **find** request
            (`/requests/create` only).
      description: >
        Mirrors `requestLawsuitsInputSchema` in `@judit-io/miner-shared` (strict
        object).


        Cross-field rules (enforced server-side):

        - If both `amount_min` and `amount_max` are set, `amount_min` ≤
        `amount_max`.

        - For `sentence-execution`: `budget_years` and `natures` must be absent.

        - For `judgement-bond`: `tags` must be absent.

        - `amount_tier` cannot be used together with `amount_min` or
        `amount_max`.
    CountRequestSuccess:
      type: object
      required:
        - request_id
        - total_lawsuits
        - status
      properties:
        request_id:
          type: integer
          format: int64
        total_lawsuits:
          type: integer
          minimum: 0
        status:
          $ref: '#/components/schemas/RequestStatus'
        filter:
          $ref: '#/components/schemas/StoredRequestFilter'
    LawsuitKind:
      type: string
      enum:
        - judgement-bond
        - sentence-execution
    AmountTier:
      type: string
      enum:
        - 0-100k
        - 100k-250k
        - 250k-500k
        - 500k-750k
        - 750k-1.5M
        - 1.5M+
    LawsuitNature:
      type: string
      enum:
        - alimentary
        - common
    LawsuitTag:
      type: string
      enum:
        - precatory_dispatched
        - possible_precatory
        - possible_approved_calculation
    RequestStatus:
      type: string
      enum:
        - pending
        - completed
        - failed
    StoredRequestFilter:
      type: object
      description: Subset of filters returned on GET request (when stored on the entity)
      properties:
        kind:
          $ref: '#/components/schemas/LawsuitKind'
        tribunals:
          type: array
          items:
            type: integer
        amount_min:
          type: number
        amount_max:
          type: number
        budget_years:
          type: array
          items:
            type: integer
        natures:
          type: array
          items:
            $ref: '#/components/schemas/LawsuitNature'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/LawsuitTag'
    ErrorPayload:
      type: object
      description: >
        Shape depends on `@judit-io/server` error serialization; typically
        includes

        machine-readable codes or message lists. Treat as opaque unless you
        confirm

        against your gateway.
      additionalProperties: true
      properties:
        errors:
          type: array
          items:
            type: string
  responses:
    BadRequest:
      description: Validation failed (Zod); `errors` is a list of human-readable messages.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorPayload'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api-key
      description: >-
        Replace with the actual API key requirement for your Miner API
        deployment.

````