Skip to main content
Use this endpoint to check the progress of an asynchronous bulk export or import job. Poll this endpoint until status is completed or failed. For completed export jobs, the response includes a downloadUrl — a pre-signed S3 URL valid for one hour. For import jobs, check the errors array for any records that were skipped.

​
Request

GET https://api.clinikapi.com/v1/bulk/jobs/:jobId

​
Headers

​
x-api-key
string
required
Your ClinikAPI secret key (clk_live_* or clk_test_*).

​
Path parameters

​
jobId
string
required
The job ID returned by the bulk export or import endpoint (e.g. job_abc123).

​
Response

Returns 200 OK with the current job state wrapped in the standard envelope.
​
data.id
string
Job ID.
​
data.type
string
Job type: export or import.
​
data.status
string
Current job status. One of: pending, processing, completed, failed.
​
data.totalRecords
number
Total number of records to process (populated once the job begins processing).
​
data.processedRecords
number
Number of records processed so far.
​
data.downloadUrl
string
Pre-signed S3 URL to download the NDJSON export file. Present only when type is export and status is completed. Valid for one hour.
​
data.errors
array
Array of error objects for any records that failed during processing. Each entry includes a record index and error message.
​
meta
object
Standard response metadata including requestId, timestamp, status, and rate-limit fields.

​
Job status values

StatusDescription
pendingJob is queued and waiting to run.
processingJob is actively running.
completedJob finished successfully.
failedJob encountered a fatal error. Check errors for details.

​
Examples

​
curl

curl https://api.clinikapi.com/v1/bulk/jobs/job_abc123 \
  -H "x-api-key: clk_live_abc123"

{
  "data": {
    "id": "job_abc123",
    "type": "export",
    "status": "completed",
    "totalRecords": 1250,
    "processedRecords": 1250,
    "downloadUrl": "https://s3.amazonaws.com/clinikapi-exports/job_abc123.ndjson?...",
    "errors": []
  }
}

​
TypeScript SDK

import { Clinik } from '@clinikapi/sdk';

const clinik = new Clinik(process.env.CLINIKAPI_SECRET_KEY!);

// Poll until the job is done
let job;
do {
  await new Promise(r => setTimeout(r, 3000));
  ({ data: job } = await clinik.bulk.getJob('job_abc123'));
} while (job.status === 'pending' || job.status === 'processing');

if (job.status === 'completed') {
  console.log(job.downloadUrl);      // fetch and stream this URL
  console.log(job.processedRecords); // 1250
} else {
  console.error('Job failed:', job.errors);
}