> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get batch job status

> Poll batch import job status and counters by jobId across entity, transaction, and user-event imports.

## Endpoint

```
GET https://api.gu1.ai/batch-import/jobs/{jobId}
```

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

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

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

## Query parameters

| Parameter | Description                                                                                                                                                                                                                             |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `include` | Optional comma-separated list. Use `include=failures` to return the same JSON body as the kind-specific failures endpoint (row-level `failures[]`, `skips[]` for entities, etc.). Omit for a lightweight status payload during polling. |

## HTTP responses

| Status | When                                                   |
| ------ | ------------------------------------------------------ |
| `200`  | Job found                                              |
| `401`  | Not authenticated                                      |
| `403`  | Missing batch-import permission                        |
| `404`  | Unknown `jobId` or job belongs to another organization |

## Recommended polling flow

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](/en/api-reference/bulk-imports/overview)).

<Note>
  For listing recent jobs (dashboard-style), use [Unified history](/en/api-reference/bulk-imports/list-unified-history). For polling a single job, prefer this endpoint.
</Note>

## JSON response (default — status only)

```json theme={null}
{
  "success": true,
  "job": {
    "jobId": "550e8400-e29b-41d4-a716-446655440000",
    "kind": "entity_automatic",
    "status": "running",
    "totalItems": 100,
    "succeeded": 45,
    "failed": 2,
    "skipped": 1,
    "heartbeatAt": "2026-06-26T12:00:00.000Z",
    "leaseExpiresAt": "2026-06-26T12:10:00.000Z",
    "workerError": null,
    "createdAt": "2026-06-26T11:59:00.000Z",
    "completedAt": null,
    "metadata": { "fileName": "entities.csv" }
  }
}
```

<ResponseField name="success" type="boolean">Always `true` when the job exists.</ResponseField>

<ResponseField name="job.jobId" type="string">Batch job identifier from the upload response.</ResponseField>

<ResponseField name="job.kind" type="string">`entity_automatic`, `transaction_batch`, or `user_event_batch`.</ResponseField>

<ResponseField name="job.status" type="string">`queued`, `running`, `completed`, `failed`, `cancelled`, or `interrupted`. While a cancel is in progress the job may still show `running` with `metadata.batchCancelRequested`.</ResponseField>

<ResponseField name="job.totalItems" type="number | null">Total rows/items in the job.</ResponseField>

<ResponseField name="job.succeeded" type="number | null">Successfully processed count.</ResponseField>

<ResponseField name="job.failed" type="number | null">Failed row count.</ResponseField>

<ResponseField name="job.skipped" type="number | null">Skipped row count (e.g. duplicate taxId on entity imports).</ResponseField>

<ResponseField name="job.heartbeatAt" type="string | null">Last worker heartbeat (ISO 8601).</ResponseField>

<ResponseField name="job.leaseExpiresAt" type="string | null">Worker lease expiry (ISO 8601).</ResponseField>

<ResponseField name="job.workerError" type="string | null">Truncated worker error when the job failed at job level.</ResponseField>

<ResponseField name="job.createdAt" type="string">Job creation time (ISO 8601).</ResponseField>

<ResponseField name="job.completedAt" type="string | null">Completion time when terminal (ISO 8601).</ResponseField>

<ResponseField name="job.metadata" type="object | null">Job metadata (e.g. `fileName`, import mode).</ResponseField>

<ResponseField name="job.jobFailure" type="object | null">Present when `status` is `failed` and the whole job aborted. Includes stable `code` and `message` — see [Failure codes](/en/api-reference/bulk-imports/batch-import-failure-codes).</ResponseField>

## JSON response with `?include=failures`

Same contract as the kind-specific failures JSON endpoints:

* Entities: [Entity batch failures](/en/api-reference/bulk-imports/get-entity-batch-failures)
* Transactions: [Transaction batch failures](/en/api-reference/bulk-imports/get-transaction-batch-failures)
* User events: [User-event batch failures](/en/api-reference/bulk-imports/get-user-event-batch-failures)

When there are no row failures, `failures` is an empty array (`failuresTotal: 0`).

See also: [Bulk imports overview](/en/api-reference/bulk-imports/overview), [Unified history](/en/api-reference/bulk-imports/list-unified-history).