---
title: "List Batches"
method: GET
path: "/batches"
tags: ["batches"]
---

# List Batches

`GET /batches`

## Request

- Base URL: `https://api.licenscheck.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.licenscheck.com/batches`
- Auth: none declared

List the key's batches that were run, newest first (kept 90 days).

Args:
    limit: Max batches to return.
    key: Injected: the caller's paid key.
    batches: Injected `BatchRepository`.
    keys: Injected `ApiKeyRepository`.

Returns:
    The batches.

## Query parameters

- `limit` integer: Max batches to return.

## Response `200`

Successful Response

- BatchListOut: Response for GET /batches.
  - `batches` BatchOut[], required: The key's batches that were run, newest first.
    - `id` string, uuid, required: The batch's ID.
    - `filename` string, required: The uploaded file's name.
    - `status` 'draft' | 'queued' | 'running' | 'done' | 'failed', required: Where a batch verification is: uploaded, waiting, being verified, or finished. Attributes: DRAFT: Uploaded and matched, waiting for the customer to confirm the columns and cost. QUEUED: Confirmed; waiting for a worker. RUNNING: A worker is reading each matched row's verdict. DONE: Every matched row has its verdict. FAILED: The worker gave up on it; rows verified before that keep their results.
    - `columns` ColumnOut[], required: The file's columns, in order.
      - `name` string, required: The header.
      - `sample` string, required: The first row's value in it.
      - `role` 'license_number' | 'name' | 'state' | 'keep', required: What one uploaded column holds, as the customer confirmed it. Attributes: LICENSE_NUMBER: The license number. NAME: The licensee or business name. STATE: The license's state. KEEP: Anything else: passed through to the results untouched.
    - `rows` integer, required: Data rows in the file.
    - `matched` integer, required: Rows matched to one contractor: verified, one verification each.
    - `ambiguous` integer, required: Rows several contractors could be: never charged until you pick one.
    - `not_found` integer, required: Rows no license matches: never charged.
    - `invalid` integer, required: Rows with no usable number or name, or an unknown state: never charged.
    - `with_number` integer, required: Rows with a license number.
    - `processed` integer, required: Matched rows verified so far.
    - `levels` object, required: Verified rows by verdict: clear, review, risk.
    - `verifications` integer, required: New verifications the batch has used.
    - `created_at` string, date-time, required: When it was uploaded.
    - `finished_at` string, date-time, nullable, required: When it finished, if it has.
    - `cost` CostOut, required: What running the batch will use, before it runs.
      - `verifications` integer, required: New verifications it needs: each matched license once, less those already verified today.
      - `already_verified` integer, required: Matched licenses verified today already: free again.
      - `included_left` integer, nullable, required: Verifications left on the plan this month; null for no cap.
      - `overage_cents` integer, nullable, required: Each verification past those, in US cents.
      - `max_cost_cents` integer, nullable, required: The most running it can add to the bill, in US cents; null for no cap.

## Other responses

- `401`: No API key, or one that's wrong or revoked.
- `403`: A free key: batches need a paid plan.
- `422`: Validation Error

---

[API](https://skmtc.dev/licenscheck/apis/licenscheck-api.md) · [All operations](https://skmtc.dev/licenscheck/apis/licenscheck-api/llms.txt) · [OpenAPI document](https://skmtc.dev/licenscheck/apis/licenscheck-api/revisions/472db933f385?raw)