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

# Get a request status

> Returns metadata and status (pending, completed, failed) for a request by its request_id. Use it to poll processing until completion.



## OpenAPI

````yaml openapi/miner.yaml GET /requests/{request_id}
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/{request_id}:
    get:
      tags:
        - Requests
      summary: Get one request by ID for the current company
      description: |
        Returns request metadata and, when present, a subset of stored filters.
        **404** if the request does not exist for the company.
      operationId: getRequestById
      parameters:
        - name: request_id
          in: path
          required: true
          description: Numeric request identifier
          schema:
            type: integer
            format: int64
            minimum: 1
      responses:
        '200':
          description: Request found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindOneRequestSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    FindOneRequestSuccess:
      type: object
      required:
        - request_id
        - status
        - type
        - total_lawsuits
        - created_at
        - updated_at
      properties:
        request_id:
          type: integer
          format: int64
        status:
          $ref: '#/components/schemas/RequestStatus'
        type:
          $ref: '#/components/schemas/RequestType'
        total_lawsuits:
          type: integer
        processed_lawsuits:
          type: integer
          description: Present when truthy in persistence layer
        error_message:
          type: string
        filter:
          $ref: '#/components/schemas/StoredRequestFilter'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    RequestStatus:
      type: string
      enum:
        - pending
        - completed
        - failed
    RequestType:
      type: string
      enum:
        - count
        - find
    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
    LawsuitKind:
      type: string
      enum:
        - judgement-bond
        - sentence-execution
    LawsuitNature:
      type: string
      enum:
        - alimentary
        - common
    LawsuitTag:
      type: string
      enum:
        - precatory_dispatched
        - possible_precatory
        - possible_approved_calculation
  responses:
    BadRequest:
      description: Validation failed (Zod); `errors` is a list of human-readable messages.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorPayload'
    NotFound:
      description: Resource not found (e.g. `REQUEST_NOT_FOUND`)
      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.

````