Jobs and artifacts

Every slow /v1 call returns a Job. wait_seconds is a query parameter. Idempotency-Key is a header. Each automatic search or QA turn has one job for its answer, including all the metadata, reading, SQL, and ask-file work performed inside it. A qa-file or query-tables call you make yourself has its own job; its response includes job_id for retrieving it later.

Python
TypeScript
curl

from ndi_sdk import NdiClient

with NdiClient() as client:
    upload = client.documents.create_upload("report.pdf")
    queued = client.documents.parse(upload)
    job = client.jobs.wait(queued.job_id, timeout=600)
    print(job.status, job.result.markdown)

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

import { NdiClient } 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 });
console.log(job.status, job.result);

for await (const event of client.jobs.events(job.job_id)) {
  console.log(event);
}

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"

Inspect and cancel

Action	Python	TypeScript	HTTP
Get	`jobs.get`	`jobs.get`	`GET /v1/jobs/{id}`
List	`jobs.list` / `iter_all`	`jobs.list` / `iterAll`	`GET /v1/jobs`
Cancel	`jobs.cancel`	`jobs.cancel`	`POST /v1/jobs/{id}/cancel`
Echo request	`jobs.request`	HTTP only	`GET /v1/jobs/{id}/request`
Delete	`jobs.delete`	HTTP only	`DELETE /v1/jobs/{id}`
SSE	`jobs.events`	`jobs.events`	`GET /v1/jobs/{id}/events`

A cancelled job is not charged, except for results already delivered before the cancel, and returns no results: result is null and result_state reads cancelled, including progressive values published before the cancel and an automatic search’s delegated job. See Cancellation. jobs.request returns the document-operation payload a finished run was asked for. It raises invalid_request for kinds that have no single document request (search jobs) and result_expired when retention dropped the payload. jobs.delete hides the row from lists and deletes its content (input, result and artifact files) within minutes. The job still reads by id with deleted_at set, and its units still count toward usage. Once the content is removed, result_state reads expired. A running job is cancelled first. If another retained job reused this job’s Parse result, only the artifact files that job still uses stay, until its own content expires. PATCH /v1/jobs/{id} is REST-only (no SDK wrapper).

Artifacts

Authenticated fetches, same API key:

Ground crops — jobs.ground_crop / GET /v1/jobs/{id}/ground-crops/{ref}
Ground transcripts — GET /v1/jobs/{id}/ground-transcript/{ref}
Parse transcripts — GET /v1/jobs/{id}/parse-transcript/{ref} (audio/video MediaTimeline)
Converted PDF — GET /v1/jobs/{id}/converted-pdf/{ref} (Office sources rendered for overlay geometry)
Spreadsheet cell maps — GET /v1/jobs/{id}/spreadsheet-cell-maps/{ref} (rendered table axes to physical cells)

When payload_expires_at passes, GET /v1/jobs/{id} still exists but result is gone (result_expired).

Usage

from datetime import date

from ndi_sdk import NdiClient

with NdiClient() as client:
    usage = client.jobs.usage(
        period_start=date(2026, 8, 1),
        period_end=date(2026, 9, 1),
        group_by="day",
    )
    print(usage)

GET /v1/usage/overview is HTTP-only. See Jobs and idempotency and Processing units.

Getting started

Guides

Agents

Concepts

Troubleshooting

Inspect and cancel

Artifacts

Usage

​Inspect and cancel

​Artifacts

​Usage

Inspect and cancel

Artifacts

Usage