Job management

Slow NDI operations return a Job. You can wait for completion, read the latest state, stream progress, cancel active work, or list past jobs through client.jobs.

Submit and wait

import { NdiClient, isParseResult } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("report.pdf");
const queued = await client.documents.parse(upload);
const job = await client.jobs.wait(queued.job_id, { timeout: 600 });

if (isParseResult(job.result)) {
  console.log(job.status, job.result.markdown);
}

jobs.wait polls until the job is terminal. Its default timeout is 300 seconds. A timeout stops waiting but does not cancel the server-side job.

Choose inline wait or polling

Job-creating methods accept wait_seconds. This asks the server to hold the submission response open for up to 300 seconds:

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("report.pdf");
let job = await client.documents.parse(upload, { wait_seconds: 30 });

if (!job.is_terminal) {
  job = await client.jobs.wait(job.job_id, { timeout: 600 });
}

The document method returns a Job whether the work finishes inline or keeps running. wait_seconds is a server-side hold-open window. The timeout passed to jobs.wait is the SDK’s total polling budget. Neither timeout cancels the job.

Retrieve job status

Use jobs.get when you control polling or need the latest state once.

import { JobStatus, NdiClient } from "ndi-sdk";

const client = new NdiClient();
const jobId = "550e8400-e29b-41d4-a716-446655440003";
const job = await client.jobs.get(jobId);

if (job.status === JobStatus.SUCCEEDED) {
  console.log(job.result);
} else if (job.status === JobStatus.FAILED) {
  console.log(job.error);
} else {
  console.log(`Still ${job.status}`);
}

Status	Meaning
`queued`	Accepted and waiting to start
`running`	Processing
`succeeded`	Result is ready
`failed`	Processing ended with `job.error`
`cancelled`	The job was cancelled

Treat status values as open-ended. Use job.is_terminal or the exported JobStatus members instead of assuming this table can never grow.

Handle failures and timeouts

By default, jobs.wait throws JobFailedError for failed or cancelled jobs and JobTimeoutError when its local wait budget expires. Both errors carry the last job state.

import { JobFailedError, JobTimeoutError } from "ndi-sdk";

const jobId = "550e8400-e29b-41d4-a716-446655440003";

try {
  const job = await client.jobs.wait(jobId, { timeout: 600 });
  console.log(job.status);
} catch (err) {
  if (err instanceof JobFailedError) {
    console.error(err.job.status, err.job.error);
  } else if (err instanceof JobTimeoutError) {
    console.log(`${err.job.job_id} is still ${err.job.status}`);
  } else {
    throw err;
  }
}

Set raise_on_failure: false when you prefer to inspect a failed or cancelled job as a normal return value.

import { JobStatus } from "ndi-sdk";

const jobId = "550e8400-e29b-41d4-a716-446655440003";
const job = await client.jobs.wait(jobId, { raise_on_failure: false });
if (job.status !== JobStatus.SUCCEEDED) {
  console.log(job.error);
}

Cancel a job

const jobId = "550e8400-e29b-41d4-a716-446655440003";
const cancelled = await client.jobs.cancel(jobId, {
  reason: "The source document was replaced",
});
console.log(cancelled.status);

Only queued or running jobs can be cancelled. Cancelling a terminal job throws ConflictError with code job_not_cancellable.

List and paginate jobs

jobs.list returns one cursor page, newest first. Filter by workspace, kind, status, or creation time.

import { JobKind, JobStatus, NdiClient } from "ndi-sdk";

const client = new NdiClient();
const page = await client.jobs.list({
  kind: [JobKind.PARSE],
  status: [JobStatus.SUCCEEDED],
  created_after: new Date("2026-09-01T00:00:00Z"),
  limit: 50,
});

for (const job of page.items) {
  console.log(job.job_id, job.created_at);
}

Use iterAll to traverse every page without managing cursors.

const workspaceId = "550e8400-e29b-41d4-a716-446655440001";

for await (const job of client.jobs.iterAll({ workspace_id: workspaceId })) {
  console.log(job.job_id, job.status);
}

Stream progress

jobs.events yields Server-Sent Events until the job becomes terminal or the server closes the stream.

const jobId = "550e8400-e29b-41d4-a716-446655440003";

for await (const event of client.jobs.events(jobId)) {
  console.log(event.status, event.message);
}

Events are a latency convenience, not a completion guarantee. Always confirm the final state with jobs.get or jobs.wait. Pass last_event_id when reconnecting to continue the event sequence.

const jobId = "550e8400-e29b-41d4-a716-446655440003";
const lastEventId = "12";

for await (const event of client.jobs.events(jobId, {
  last_event_id: lastEventId,
})) {
  console.log(event);
}

Result retention

The job row can outlive its result payload. Check job.result_state before using an older result. When retention has removed the payload, artifact reads throw ResultExpiredError.

The TypeScript SDK does not currently wrap GET /v1/jobs/{id}/request, DELETE /v1/jobs/{id}, or PATCH /v1/jobs/{id}. Call those REST endpoints directly when you need request inspection, soft deletion, or updates.

Methods

get(job_id: string): Promise<Job>
list(opts?: { workspace_id?, kind?, status?, created_after?, cursor?, limit? }): Promise<Page<Job>>
iterAll(opts?: { workspace_id?, kind?, status?, created_after?, limit? }): AsyncGenerator<Job>
wait(job_id: string, opts?: { timeout?: number; raise_on_failure?: boolean }): Promise<Job>
cancel(job_id: string, opts?: { reason?: string }): Promise<Job>
events(job_id: string, opts?: { last_event_id?: string }): AsyncGenerator<JobEvent>
groundCrop(job_id: string, artifact_ref: string, opts?: { byte_range?: string }): Promise<Uint8Array>
usage(opts: { period_start: Date | string; period_end: Date | string; workspace_id?: string; group_by?: "day" | "kind" | "workspace" }): Promise<UsageResponse>

Get started

Core methods

Async and utilities

Submit and wait

Choose inline wait or polling

Retrieve job status

Handle failures and timeouts

Cancel a job

List and paginate jobs

Stream progress

Result retention

Methods

Next steps

​Submit and wait

​Choose inline wait or polling

​Retrieve job status

​Handle failures and timeouts

​Cancel a job

​List and paginate jobs

​Stream progress

​Result retention

​Methods

​Next steps

Submit and wait

Choose inline wait or polling

Retrieve job status

Handle failures and timeouts

Cancel a job

List and paginate jobs

Stream progress

Result retention

Methods

Next steps