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

# List License Renewal Batches

> Renewal groups, each covering several licence requests

Returns renewal batches: a group is one renewal run covering several licence requests, with a shared status and payment.

Use [List License Requests](/api-reference/v2/downstream/license-requests/list-license-requests) for the individual requests inside a batch.


## OpenAPI

````yaml openapi/v2.json GET /v2/downstream/license-request-groups
openapi: 3.0.0
info:
  title: Turris Public API
  description: API for managing insurance compliance data
  version: 2.0.0
  contact: {}
servers:
  - url: https://public.api.live.turrisfi.com
    description: Production
  - url: https://public.api.sandbox.turrisfi.com
    description: Sandbox
security: []
tags: []
paths:
  /v2/downstream/license-request-groups:
    get:
      tags:
        - downstream/license-requests
      summary: List license renewal batches
      description: >-
        Returns the renewal batches your organization has submitted, with their
        status and total fee. The individual applications are on the List
        License Requests endpoint, carrying this batch as groupId. Payment is
        summarised rather than exposed: amount, status and paid-at only. Results
        are paginated, newest first.
      operationId: LicenseRequestsController_getLicenseRequestGroups_v2
      parameters:
        - name: page
          required: false
          in: query
          description: 1-based page number
          schema:
            minimum: 1
            default: 1
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Page size (max 100)
          schema:
            minimum: 1
            maximum: 100
            default: 50
            example: 50
            type: number
        - name: downstreamEntityId
          required: false
          in: query
          description: >-
            Narrow the results to a single entity in your organization. Defaults
            to your whole subtree (your entity plus every branch beneath it).
            Returns 404 if the id is not in your subtree.
          schema:
            example: 6610b3d2c2e0a51b8c0d1f02
            type: string
        - name: status
          required: false
          in: query
          description: Batch status
          schema:
            example: submitted
            type: string
            enum:
              - processing
              - submitting
              - pending input
              - submitted
              - partially submitted
              - completed
              - failed
              - cancelled
              - pending review
              - in progress
      responses:
        '200':
          description: A page of renewal batches
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: >-
                            #/components/schemas/DownstreamLicenseRequestGroupResponse
                      total:
                        type: integer
                        description: Total rows matching the query across all pages
                        example: 137
                      page:
                        type: integer
                        description: 1-based page number
                        example: 1
                      limit:
                        type: integer
                        description: Page size
                        example: 50
                      totalPages:
                        type: integer
                        description: Number of pages, or 0 when there are no rows
                        example: 3
                    required:
                      - items
                      - total
                      - page
                      - limit
                      - totalPages
                  requestId:
                    type: string
                    description: Unique request identifier
                    example: dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8
                  timestamp:
                    type: string
                    description: Response timestamp
                    example: '2025-11-12T20:49:03.293Z'
                required:
                  - data
                  - requestId
                  - timestamp
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '401':
          description: Invalid or missing auth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '403':
          description: Your organization is not entitled to the public API
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '404':
          description: downstreamEntityId is not in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
components:
  schemas:
    DownstreamLicenseRequestGroupResponse:
      type: object
      properties:
        groupId:
          type: string
          description: Unique identifier of the batch
          example: 6627f2b5c2e0a51b8c0d4e90
        downstreamEntityId:
          type: string
          description: The agency that submitted the batch
          example: 6610b3d2c2e0a51b8c0d1f02
        status:
          type: string
          description: Batch status
          enum:
            - processing
            - submitting
            - pending input
            - submitted
            - partially submitted
            - completed
            - failed
            - cancelled
            - pending review
            - in progress
          example: submitted
        paymentStatus:
          type: string
          description: Payment status of the batch
          enum:
            - unpaid
            - processing
            - requires action
            - paid
          example: paid
        totalFeeAmount:
          type: number
          description: Total fee for the batch, in the smallest currency unit
          example: 22000
        paidAt:
          type: string
          description: ISO 8601 timestamp the batch was paid
          example: '2026-01-15T10:40:00.000Z'
        submittedAt:
          type: string
          description: ISO 8601 timestamp the batch was submitted
          example: '2026-01-15T10:41:00.000Z'
        completedAt:
          type: string
          description: ISO 8601 timestamp the batch completed
          example: '2026-01-18T09:02:00.000Z'
        createdAt:
          type: string
          description: ISO 8601 creation timestamp
          example: '2026-01-15T10:30:00.000Z'
      required:
        - groupId
        - downstreamEntityId
        - status
        - paymentStatus
    ErrorResponseDto:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code
        requestId:
          type: string
          description: Unique request identifier for debugging
        errorType:
          type: string
          description: >-
            Machine-readable error classification. Branch on this rather than on
            `errorMessage`, which is prose and may change. Authentication
            failures returned by our identity provider are forwarded verbatim,
            so a 401 can carry a code outside this list; treat an unrecognised
            value as a generic failure of its HTTP status.
          enum:
            - conflict
            - contact_not_authorized
            - document_exceeds_page_limit
            - downstream_entity_member_exists
            - duplicate_external_id_error
            - duplicate_member_email
            - duplicate_producer_code_error
            - forbidden
            - gateway_timeout
            - inactive_email
            - internal_server_error
            - invalid_email
            - invalid_email_for_invites
            - invalid_organization_category
            - invalid_organization_slug
            - invalid_phone_number
            - invalid_token
            - invite_limit_reached
            - jwt_invalid
            - m2m_client_not_found
            - not_found
            - organization_already_exists
            - organization_slug_already_used
            - payment_required
            - producer_agreement_required
            - product_feature_subscription_required
            - service_unavailable
            - session_authorization_error
            - some_custom_error_string
            - throttled
            - too_many_requests
            - unauthorized
            - unauthorized_client
            - unexpected_400_stytch_error
            - unexpected_403_stytch_error
            - unexpected_404_stytch_error
            - unexpected_error
            - unexpected_stytch_error
            - unprocessable_entity
            - validation_error
          example: validation_error
        errorMessage:
          description: Array of error messages
          type: array
          items:
            type: string
        timestamp:
          type: string
          description: ISO timestamp when the error occurred
        details:
          type: object
          description: Additional error context
      required:
        - statusCode
        - requestId
        - errorType
        - errorMessage
        - timestamp

````

## Related topics

- [Webhooks Overview](/guides/webhooks.md)
- [List License Requests](/api-reference/v2/downstream/license-requests/list-license-requests.md)
- [Changelog](/changelog.md)