---
title: "Poll batch job status"
method: GET
path: "/v1/batches/{batch_id}"
tags: ["Batches"]
---

# Poll batch job status

`GET /v1/batches/{batch_id}`

## Request

- Base URL: `https://api.scholarfeed.org` (the document declares no server; this is the origin it was published from)
- URL: `https://api.scholarfeed.org/v1/batches/{batch_id}`
- Auth: HTTP bearer

Poll the status, request_counts, and results of a batch job.

Returns the current job state for the authenticated account's job.
Account-scoped: a `batch_id` belonging to a different account returns 404
(no cross-account information leakage).

For the foreseeable future, `status` will remain `"queued"` because the
processing worker (BATCH2-01) is not yet active — submitted batches are
not processed until the worker ships.

`results` is populated only when `status="completed"`, directly from the
`results` JSONB column on `batch_jobs`. Until the worker ships, `results`
will always be null.

Returns 404 for unknown batch ids, invalid UUIDs, or jobs belonging to
other accounts (account-scoped, no 403/422 distinction to avoid leaking
existence information).
Returns 401 if not authenticated.

## Path parameters

- `batch_id` string, required

## Response `200`

Successful Response

- ApiRoutersBatchesBatchStatusResponse: Response from GET /v1/batches/{batch_id} — current job state.
  - `id` string, required: UUID of the batch job.
  - `status` string, required: Current job lifecycle status: queued | running | completed | failed | cancelled | expired. For the foreseeable future status will remain 'queued' because the processing worker (BATCH2-01) is not yet active — submitted batches are not processed until the worker ships.
  - `request_counts` object, required: Running operation counts: {total, completed, failed}. Reflects the submitted operation count; completed/failed update as the worker progresses (worker not yet active).
  - `results` object, nullable: Per-operation results array populated by the worker on completion. Null until status='completed'. Stored in the results JSONB column on batch_jobs — no external object storage.
  - `created_at` string, nullable: ISO8601 timestamp when the job was created.
  - `started_at` string, nullable: ISO8601 timestamp when a worker claimed the job (queued → running). Null until claimed.
  - `finished_at` string, nullable: ISO8601 timestamp when the job reached a terminal status. Null until terminal.
  - `expires_at` string, nullable: ISO8601 timestamp when results may be evicted by a sweep job. Null = no expiry set.
  - `error` string, nullable: Terminal failure detail. Set when status='failed' or 'expired'. Null otherwise.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/scholarfeed/apis/scholar-feed-api.md) · [All operations](https://skmtc.dev/scholarfeed/apis/scholar-feed-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scholarfeed/apis/scholar-feed-api/revisions/fc3200d27505?raw)