Batches

Poll batch job status

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.

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

Path parameters

batch_idstring required

Response

Successful Response

idstring required

UUID of the batch job.

statusstring 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_countsobject required

Running operation counts: {total, completed, failed}. Reflects the submitted operation count; completed/failed update as the worker progresses (worker not yet active).

resultsobject 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_atstring nullable

ISO8601 timestamp when the job was created.

started_atstring nullable

ISO8601 timestamp when a worker claimed the job (queued → running). Null until claimed.

finished_atstring nullable

ISO8601 timestamp when the job reached a terminal status. Null until terminal.

expires_atstring nullable

ISO8601 timestamp when results may be evicted by a sweep job. Null = no expiry set.

errorstring nullable

Terminal failure detail. Set when status='failed' or 'expired'. Null otherwise.

Changes