Skip to main content
GET
/
batch-import
/
jobs
/
{jobId}
Get batch job status
curl --request GET \
  --url http://api.gu1.ai/batch-import/jobs/{jobId} \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "job.jobId": "<string>",
  "job.kind": "<string>",
  "job.status": "<string>",
  "job.totalItems": {},
  "job.succeeded": {},
  "job.failed": {},
  "job.skipped": {},
  "job.heartbeatAt": {},
  "job.leaseExpiresAt": {},
  "job.workerError": {},
  "job.createdAt": "<string>",
  "job.completedAt": {},
  "job.metadata": {},
  "job.jobFailure": {}
}

​
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

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

​
Query parameters

ParameterDescription
includeOptional 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

StatusWhen
200Job found
401Not authenticated
403Missing batch-import permission
404Unknown jobId or job belongs to another organization
  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)

{
  "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" }
  }
}
​
success
boolean
Always true when the job exists.
​
job.jobId
string
Batch job identifier from the upload response.
​
job.kind
string
entity_automatic, transaction_batch, or user_event_batch.
​
job.status
string
queued, running, completed, failed, cancelled, or interrupted. While a cancel is in progress the job may still show running with metadata.batchCancelRequested.
​
job.totalItems
number | null
Total rows/items in the job.
​
job.succeeded
number | null
Successfully processed count.
​
job.failed
number | null
Failed row count.
​
job.skipped
number | null
Skipped row count (e.g. duplicate taxId on entity imports).
​
job.heartbeatAt
string | null
Last worker heartbeat (ISO 8601).
​
job.leaseExpiresAt
string | null
Worker lease expiry (ISO 8601).
​
job.workerError
string | null
Truncated worker error when the job failed at job level.
​
job.createdAt
string
Job creation time (ISO 8601).
​
job.completedAt
string | null
Completion time when terminal (ISO 8601).
​
job.metadata
object | null
Job metadata (e.g. fileName, import mode).
​
job.jobFailure
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.