---
title: "Poll an async batch job for status and results"
method: GET
path: "/v1/batch/{batch_id}"
tags: ["Batch"]
---

# Poll an async batch job for status and results

`GET /v1/batch/{batch_id}`

## Request

- Base URL: `https://api.registrum.co.uk`
- URL: `https://api.registrum.co.uk/v1/batch/{batch_id}`
- Auth: API key in header `X-API-Key`

Poll for the status and results of a previously submitted batch job.

**This endpoint is free** - polling does not consume API credits.

Poll every 2–5 seconds until `status` reaches a terminal state:
`complete`, `partial`, `failed`, or `quota_exceeded`.

The `results` array grows as companies are enriched. `errors` accumulates
any failures. Once `status` is terminal, `results` and `errors` are final.

**Suggested polling interval:**
- Small batches (≤50): every 5 seconds
- Medium batches (51–200): every 10 seconds
- Large batches (201–500): every 15–30 seconds

**Example response (in-progress):**
```json
{
  "batch_id": "3fa85f64-...",
  "status": "processing",
  "total_companies": 100,
  "completed_companies": 30,
  "credits_charged": 30,
  "results": [...],
  "errors": {},
  "created_at": "2026-03-17T10:00:00Z",
  "expires_at": "2026-03-24T10:00:00Z"
}
```

## Path parameters

- `batch_id` string, required: The batch job's ID, as returned by POST /v1/batch when the job was submitted.

## Response `200`

Batch job status and partial/full results

- BatchJobStatus: Full status and results for a batch job - returned by GET /v1/batch/{batch_id}.
  - `batch_id` string, required: UUID of this batch job.
  - `status` string, required: Current processing state: - `queued` - waiting to start - `processing` - actively being enriched - `complete` - all companies successfully enriched - `partial` - finished with some errors (see `errors`) - `quota_exceeded` - your monthly quota ran out mid-batch; remaining companies are in `errors` - `failed` - all companies failed (upstream issue)
  - `total_companies` integer, required: Total number of companies in this batch.
  - `completed_companies` integer, required: Number of companies processed so far (successes + errors).
  - `credits_charged` integer, required: Credits consumed so far. Final value once status is terminal.
  - `results` object[]: Enriched profiles for successfully processed companies. Each item has `company_number`, `status: 'success'`, and `data` (the enriched profile). Order matches the original request.
  - `errors` object: Map of company_number → error message for companies that could not be enriched. Empty if all succeeded.
  - `created_at` string, required: ISO 8601 timestamp when the batch was submitted.
  - `expires_at` string, required: ISO 8601 timestamp when this job and its results will be automatically deleted (7 days after creation).

## Other responses

- `401`: Missing or invalid API key
- `404`: Batch job not found or does not belong to your API key
- `422`: Validation Error

---

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