---
title: "Run Batch"
method: POST
path: "/batches/{batch_id}/run"
tags: ["batches"]
---

# Run Batch

`POST /batches/{batch_id}/run`

## 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/{batch_id}/run`
- Auth: none declared

Run a draft: every matched row gets its verdict, one verification per license (once a day, as ever).

Rows that are ambiguous, not found or invalid are never charged. It usually finishes within a minute;
poll GET /batches/{id} for `status` and `processed`.

Args:
    batch_id: The draft.
    body: One role per column, as confirmed.
    background: Starts verifying once the response is sent.
    key: Injected: the caller's paid key.
    batches: Injected `BatchRepository`.
    licenses: Injected `LicenseRepository`, for matching.
    keys: Injected `ApiKeyRepository`.
    runner: Injected: verifies the batch in the background.

Returns:
    The queued batch.

Raises:
    HTTPException: 429 at the daily limit.

## Path parameters

- `batch_id` string, uuid, required

## Request body

- RolesIn: Body for previewing or running a batch with confirmed columns.
  - `roles` ColumnRole[], required: One role per column, in order: license_number, name, state or keep.

## Response `202`

Successful Response

- BatchOut: A batch: its file, where it is, and its rows by outcome.
  - `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.
- `404`: This key has no batch with that ID.
- `409`: It already ran.
- `422`: Validation Error
- `429`: The key has run 5 batches today.

---

[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)