Jobs, idempotency, and async semantics

All operations that take more than a moment return a Job resource. Every job-creating route accepts ?wait_seconds= to optionally block for a result.

Job states

Every job flows through these states:

State	Meaning
`queued`	Waiting for a worker
`running`	Processing
`succeeded`	`result` field is populated and retained until `payload_expires_at`
`failed`	`error` field is populated
`cancelled`	Cancelled by caller or system

Sync vs async via `wait_seconds`

The ?wait_seconds= query parameter controls blocking on each job-creating route:

Python
TypeScript
cURL

from ndi_sdk import NdiClient, UrlSource

source = UrlSource(
    url="https://example.com/report.pdf",
    file_name="report.pdf",
)

with NdiClient() as client:
    queued = client.documents.parse(source)
    inline = client.documents.parse(source, wait_seconds=120)

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

const client = new NdiClient();
const source = UrlSource({
  url: "https://example.com/report.pdf",
  file_name: "report.pdf",
});

const queued = await client.documents.parse(source);
const inline = await client.documents.parse(source, { wait_seconds: 120 });

# Immediate 202 (default: wait_seconds=0)
curl -X POST "$NDI_BASE_URL/v1/parse" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": {"type": "url", "url": "https://example.com/report.pdf", "file_name": "report.pdf"}}'
# → 202 with a queued Job

# Block up to 120 seconds for a result
curl -X POST "$NDI_BASE_URL/v1/parse?wait_seconds=120" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": {"type": "url", "url": "https://example.com/report.pdf", "file_name": "report.pdf"}}'
# → 200 if job finished in time, 202 if it didn't

Response codes:

200 — Job reached a terminal state within wait_seconds; full result is inline.
202 — Timeout before completion; poll GET /v1/jobs/{job_id}.

wait_seconds max is 300. It is always a query parameter, never a JSON body field.

Polling

Python
TypeScript
cURL

job = client.jobs.wait(job_id, timeout=600)
print(job.status, job.result)

const jobId = "550e8400-e29b-41d4-a716-446655440003";
const job = await client.jobs.wait(jobId, { timeout: 600 });
console.log(job.status, job.result);

# Poll until terminal
JOB_ID="550e8400-e29b-41d4-a716-446655440003"

STATUS=$(curl -s "$NDI_BASE_URL/v1/jobs/$JOB_ID" -H "X-API-Key: $NDI_API_KEY" | jq -r '.status')
until [[ "$STATUS" == "succeeded" || "$STATUS" == "failed" || "$STATUS" == "cancelled" ]]; do
  sleep 3
  STATUS=$(curl -s "$NDI_BASE_URL/v1/jobs/$JOB_ID" -H "X-API-Key: $NDI_API_KEY" | jq -r '.status')
done

curl -s "$NDI_BASE_URL/v1/jobs/$JOB_ID" -H "X-API-Key: $NDI_API_KEY"

Succeeded:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440003",
  "kind": "parse",
  "status": "succeeded",
  "result": {"result_type": "parse", "...": "..."},
  "units": 24,
  "credits": 24,
  "usage_final": true,
  "credit_schedule_version": 3,
  "usage_finalized_at": "2026-08-09T12:01:23Z",
  "usage": {
    "lines": [
      {"part": "parse", "quantity": 24, "unit": "page", "credits_per_unit": 1, "multiplier": 1, "credits": 24}
    ]
  },
  "created_at": "2026-08-09T12:00:00Z",
  "updated_at": "2026-08-09T12:01:23Z",
  "payload_expires_at": "2026-08-16T12:01:23Z"
}

Failed:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440003",
  "kind": "parse",
  "status": "failed",
  "error": {"code": "unsupported_file_type", "message": "...", "detail": null, "retryable": false, "request_id": "req-01j9..."},
  "units": 0,
  "credits": 0,
  "usage_final": true,
  "credit_schedule_version": 3,
  "usage_finalized_at": "2026-08-09T12:00:08Z",
  "usage": {"lines": []},
  "created_at": "2026-08-09T12:00:00Z",
  "updated_at": "2026-08-09T12:00:08Z",
  "payload_expires_at": null
}

Streaming job events

Subscribe to real-time status transitions instead of polling:

Python
TypeScript
cURL

for event in client.jobs.events(job_id):
    print(event.status, event.message)

const jobId = "550e8400-e29b-41d4-a716-446655440003";
for await (const event of client.jobs.events(jobId)) {
  console.log(event.status, event.message);
}

curl "$NDI_BASE_URL/v1/jobs/$JOB_ID/events" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Accept: text/event-stream"

Returns text/event-stream (Server-Sent Events). Each event is a small status update with sequence, at, status, and progress. It is not a full Job. The stream closes when the job reaches a terminal status. Call GET /v1/jobs/{id} to read the full job, including its result or error.

Idempotency

Use the Idempotency-Key HTTP header to make job-creating requests replay-safe:

Python
TypeScript
cURL

job = client.documents.parse(
    source,
    idempotency_key="parse-annual-report-2025-v1",
)

const job = await client.documents.parse(source, {
  idempotency_key: "parse-annual-report-2025-v1",
});

curl -X POST "$NDI_BASE_URL/v1/parse" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: parse-annual-report-2025-v1" \
  -d '{"source": {"type": "url", "url": "https://example.com/report.pdf", "file_name": "report.pdf"}}'

Behavior:

First call — Starts a new job.
Repeated calls with the same key — Returns the original job without starting a new one.
The key is scoped per API key.
The key is kept with the job for replay and is never cleared, also after the job’s content expires (see Data retention). Do not put personal data in an idempotency key. Use an opaque value such as a UUID or a hash of your own request id.

Idempotency-Key is always an HTTP header, never a JSON body field. Use for:

Retrying after a network failure (the same job is returned)
CI/CD pipelines (re-running a step is safe)

Listing jobs

Python
TypeScript
cURL

for job in client.jobs.iter_all(
    status=["succeeded"],
    kind=["parse"],
):
    print(job.job_id, job.status)

for await (const job of client.jobs.iterAll({
  status: ["succeeded"],
  kind: ["parse"],
})) {
  console.log(job.job_id, job.status);
}

curl "$NDI_BASE_URL/v1/jobs" \
  -H "X-API-Key: $NDI_API_KEY"

Returns a keyset-paginated page (newest first):

{
  "items": [...],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wOC0wOVQxMjowMDowMFoiLCJqb2JfaWQiOiIuLi4ifQ==",
  "total_count": 142
}

Pass ?cursor=<next_cursor> to retrieve the next page. Optional filters: ?status=succeeded, ?kind=parse.

Cancellation

Python
TypeScript
cURL

cancelled = client.jobs.cancel(
    job_id,
    reason="No longer needed",
)

const jobId = "550e8400-e29b-41d4-a716-446655440003";
const cancelled = await client.jobs.cancel(jobId, {
  reason: "No longer needed",
});

curl -X POST "$NDI_BASE_URL/v1/jobs/$JOB_ID/cancel" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "No longer needed"}'

Queued or running — Job is marked cancelled.
Already terminal — Refused with 409 job_not_cancellable. The job is unchanged; read it with GET /v1/jobs/{id}.

A job cancelled before it delivered anything is free: its credits are 0. Results already delivered before the cancel are billed: a progressive classify or extract that published labels or values bills those units. A cancelled job returns no results. GET /v1/jobs/{id} still returns the job, with result: null and result_state: "cancelled". That includes the labels or values a progressive classify or extract published before you cancelled it. For an automatic search, it also covers the job the search delegated to: reading that job by its id returns no result either, even if it finished before the cancel. Reads that serve a result, such as query result rows, grounding rows, QA presentations and filtered-search pages, are refused with 409 job_cancelled. Results you received before the cancel stay with you. No new download links are issued after the cancel. A link issued before it works until it expires.

Getting started

Guides

Agents

Concepts

Troubleshooting

Jobs, idempotency, and async semantics

Job states

Sync vs async via `wait_seconds`

Polling

Streaming job events

Idempotency

Listing jobs

Cancellation

​Job states

​Sync vs async via wait_seconds

​Polling

​Streaming job events

​Idempotency

​Listing jobs

​Cancellation

Job states

Sync vs async via `wait_seconds`

Polling

Streaming job events

Idempotency

Listing jobs

Cancellation