Skip to main content
GET
Get batch job status

Endpoint

Use this route as the canonical polling endpoint after any bulk import upload returns 202 with a jobId. It resolves the job kind automatically and performs a direct lookup β€” it does not scan the full import history.

Authentication

Requires at least one of: transactions:create, entities:bulk_import, events:create.

Query parameters

HTTP responses

  1. Upload (entities, transactions, or user events) β†’ store jobId from the 202 response.
  2. Poll GET /batch-import/jobs/{jobId} every 2–5 seconds.
  3. Stop when status is terminal: completed, failed, cancelled, or interrupted.
  4. If you need row-level detail, call again with ?include=failures or use the kind-specific failures endpoint (see Bulk imports overview).
For listing recent jobs (dashboard-style), use Unified history. For polling a single job, prefer this endpoint.

JSON response (default β€” status only)

boolean
Always true when the job exists.
string
Batch job identifier from the upload response.
string
entity_batch (alias entity_automatic), transaction_batch, or user_event_batch.
string
queued, running, completed, failed, cancelled, or interrupted. While a cancel is in progress the job may still show running with metadata.batchCancelRequested.
number | null
Total rows/items in the job.
number | null
Successfully processed count.
number | null
Failed row count.
number | null
Skipped row count (e.g. duplicate taxId on entity imports).
string | null
Last worker heartbeat (ISO 8601).
string | null
Worker lease expiry (ISO 8601).
string | null
Truncated worker error when the job failed at job level.
string
Job creation time (ISO 8601).
string | null
Completion time when terminal (ISO 8601).
object | null
Job metadata (e.g. fileName, import mode).
object | null
Present when status is failed and the whole job aborted. Includes stable code and message β€” see Failure codes.

JSON response with ?include=failures

Same contract as the kind-specific failures JSON endpoints: When there are no row failures, failures is an empty array (failuresTotal: 0). See also: Bulk imports overview, Unified history.