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

# List batches

> List batches visible to the caller.

Batches the caller can see (owner, org admin, approved library share, accepted direct share). Newest first. `page_size` defaults to 24, clamped to 1–100. `?search=` matches the batch name.

Optional `?thread_id=` restricts the list to batches that chat may attach — same scope as `POST /api/v2/chats/{thread_id}/batch-attachments/`.


## OpenAPI

````yaml GET /api/v2/batches/
openapi: 3.1.0
info:
  title: Abacus Docs API
  version: 1.0.0
  description: |
    REST + SSE surface for Abacus Docs on the same host as the web app
    (`https://abacusdocs.com`). Paths are `/api/v2/…`.

    Authenticate with an organisation API key (`sk-abacus-*`) as a Bearer
    token, or an Auth0 access token. Cross-tenant reads return **404**, not
    403. Page-based lists use `?page=` and `?page_size=`.

    Extraction, reprocess, schema tests, and chat turns spend credits.
    See the help centre Credits pages for rates.
  contact:
    name: Abacus Docs
    url: https://abacusdocs.com/contact
servers:
  - url: https://abacusdocs.com
    description: Production (Extract)
security: []
paths:
  /api/v2/batches/:
    get:
      tags:
        - v2/batches
      summary: List batches visible to the caller
      description: >-
        Returns the batches the authenticated user can see for their
        organization, scoped through ``_visible_batch_qs`` so owners, org-mods,
        superusers, approved org-library-share recipients, and active
        direct-share recipients all surface. Ordering is newest-first by
        ``created_at`` (with ``-id`` as a stable tiebreaker).


        Drives the chat 'Attach batch' picker modal (Phase 2 Task 9). Page-based
        pagination — ``?page=<int>&page_size=<int>``. ``page_size`` defaults to
        24 and is clamped to [1, 100]; ``page`` defaults to 1.


        Free-text search on the batch name via ``?search=<substring>``
        (case-insensitive). Empty search returns the unfiltered page.


        Optional ``?thread_id=<uuid>`` parameter additionally requires the named
        chat to belong to the same tenant, matching ``POST
        /api/v2/chats/<thread_id>/batch-attachments/`` so the picker never
        offers a batch that the attach call would refuse. With or without it the
        tenant is the request principal's org — for an API key that is the key's
        org, not its creator's — so a chat pinned to a different org yields an
        empty page rather than another tenant's batches.
      operationId: v2_batches_retrieve
      parameters:
        - in: query
          name: page
          schema:
            type: integer
          description: 1-indexed page number. Defaults to 1.
        - in: query
          name: page_size
          schema:
            type: integer
          description: Rows per page. Defaults to 24; clamped to [1, 100].
        - in: query
          name: search
          schema:
            type: string
          description: >-
            Case-insensitive substring match against ``Batch.name``. Trimmed and
            truncated to 100 characters.
        - in: query
          name: thread_id
          schema:
            type: string
          description: >-
            Optional chat thread id. Visibility always resolves against the
            caller's own organization; supplying a thread the caller does not
            own in it returns an empty page instead of the full list, matching
            the scope of ``POST /api/v2/chats/<thread_id>/batch-attachments/``.
            Use from the chat picker modal so the offered batches match what the
            attach endpoint will accept.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchPickerResponse'
          description: ''
      security:
        - extractApiKey: []
        - bearerAuth: []
        - cookieAuth: []
components:
  schemas:
    BatchPickerResponse:
      type: object
      description: |-
        Top-level response shape for GET /api/v2/batches/.

        Page-based pagination (mirrors ``batch_library_documents`` so the JS
        can reuse the same paging widget). ``has_more`` is server-computed to
        avoid the SPA inferring it from ``page * page_size < total`` (which
        would be wrong for a partial last page).
      properties:
        batches:
          type: array
          items:
            $ref: '#/components/schemas/BatchPickerRow'
        page:
          type: integer
          minimum: 1
        page_size:
          type: integer
          minimum: 1
        total:
          type: integer
          minimum: 0
        has_more:
          type: boolean
      required:
        - batches
        - has_more
        - page
        - page_size
        - total
    BatchPickerRow:
      type: object
      description: |-
        One row in the chat "Attach batch" picker modal.

        Compact projection of a Batch row keyed for the modal UI. Drops the
        schema/version chip from BatchSummarySerializer (the picker is org-wide,
        so most rows have no schema in common with the caller's open chat),
        keeps the lifecycle fields the chip needs (status, total_files,
        completed/failed counts) plus name + created_at for sort/display.
      properties:
        id:
          type: integer
        name:
          type: string
          description: >-
            User-supplied batch name; falls back to ``Batch #<id>`` when blank
            in the JS.
        status:
          type: string
        total_files:
          type: integer
        succeeded_count:
          type: integer
        failed_count:
          type: integer
        created_at:
          type: string
          format: date-time
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - completed_at
        - created_at
        - failed_count
        - id
        - name
        - status
        - succeeded_count
        - total_files
  securitySchemes:
    extractApiKey:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: |
        Organisation API key from Settings → API / `/api/keys/`. The secret is
        shown once. Send `Authorization: Bearer sk-abacus-…`. One active key
        per organisation. Ingest (`/api/v2/ingest/*`) refuses API keys — that
        surface is Auth0-only with `ingest:read` / `ingest:write` scopes.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Auth0 access token for a signed-in user. Send `Authorization: Bearer
        <token>`.

        The SPA and desktop agent use this. Prefer an organisation API key for

        server-to-server integrations.
    cookieAuth:
      type: apiKey
      in: cookie
      name: sessionid
      description: |
        Django session cookie from a browser login. Present so the web app can
        call `/api/v2` without a header. Do not rely on this for integrations.

````