deep_search

Let the agent finish the run with clarifying questions instead of an answer, when the query is genuinely ambiguous and the ambiguity materially changes the answer. The result then carries the questions in clarification_questions (and as text in clarification), with answer and reasoning null and evidences empty; answer them in the same thread via the result's session_id, with clarification_answers or a follow-up query. Off, the default, means the agent always answers with its best reading, stated in the answer.

Free-form background for the model — the engagement, the entity, what the caller already knows. It informs the answer; it does not widen or narrow which files the caller may see.

Deprecated and ignored: the service resolves the run's configuration itself. Accepted so clients released before the effort levels were retired keep working; omit it.

Deprecated and ignored: every run answers. Accepted so clients released before it was retired keep working; omit it.

Put every uploaded file under one folder subtree, workspace-relative, in the run's scope; paths, where the body takes it, adds more files. Omit both for the whole workspace.

What to answer, in the caller's own words. Stripped before its length is checked; a blank query is refused rather than run.

Continue a prior deep-search conversation: the id echoed on an earlier result's session_id. With the same folder/file scope and access grants, the agent resumes that thread's context. A changed scope or grants starts a fresh conversation and returns a new session_id; older threads without a scope snapshot also restart. Omit to start a new thread. Only the API key that started the thread may continue it; a thread whose turn is still running returns 409 session_busy.

Which console history this run belongs to. It does not pick the agent, the chassis, or the engine: an omitted value is deep_search (the public API and the Deep Search page). The NDI console sends qa or workbook so Activity and thread lists can split those skins. A follow-up (session_id) inherits the thread head's surface; a conflicting value on the follow-up body is ignored.

Deprecated and ignored: the service decides whether the knowledge graph is consulted. Accepted so clients released before it was retired keep working; omit it.

When the job row was created.

Version of the credit schedule credits were priced under. Null until usage_final is true.

Final credits billed for this job, priced once under credit_schedule_version. Null until usage_final is true. Never changes afterwards, including after payload expiry or deletion. Failed and cancelled-before-completion jobs finalize with 0 credits, including delivered parts; ones finalized before that policy keep their credits. Always null on a stage job that Automatic Search delegated: its work is billed on the parent job.

When the caller hid this run from listings, via delete_job. A soft delete: the job still reads by id and still counts toward GET /v1/usage — what it stops doing is appearing in GET /v1/jobs.

How hard this run worked, for the search kinds that carry it. A deep-search job (kind deep_search_v2) created before the effort knob was removed echoes its requested level: 'low', 'medium', or 'high'; newer deep-search jobs, which all run one configuration, read null. An intelligent_search row carries an internal selector instead: 'fast' is fact-search, 'automatic' is automatic-search, and 'deep' (or the legacy 'balanced') is a deep-search or console QA chat job created before the 2026-09 consolidation — those two are not distinguishable by this field. Null for every other kind. Read from the stored request, so it rides the same retention path as query and result: null once result_state leaves available.

When the job reached a terminal status.

The request's own force flag, echoed regardless of outcome. Present for kinds whose request carries one (e.g. kg_build, where a true value cleared the durable store before the job ran) so a caller can tell that apart from a build that failed leaving the prior store untouched — result alone cannot, since it is absent on failure either way.

Key that was replayed to return this job. Absent when the create call had no Idempotency-Key.

Server-minted id. Poll GET /v1/jobs/{job_id} or pass wait_seconds on create.

What a job is doing. Open enum — a new member is additive.

Display name (the console's 'project'). Public Parse, Split, Classify, Extract, and Ground runs supply a stable server default when blank; citation-generated Ground jobs are excluded. mutable via PATCH /v1/jobs/{job_id}.

Cleanup deadline after explicit deletion. Null for retained content; Zero retention uses its delivery window.

Caller-minted grouping id shared by jobs submitted together. Filterable on GET /v1/jobs.

The question this job was asked, for the search kinds that carry one (intelligent_search, qa_file, qa_tables, filtered_search); null for every other kind. Read from the stored request, so it rides the same retention path as result: null once result_state leaves available. Narrow by design — the frozen access context never reaches the wire. File scope is summarised separately as query_scope.

True only on an idempotent replay response. No new charge is made; credits remains the original job's cost.

Why Job.result is null.

available with a null result means the job has not succeeded yet; expired means its content was removed; not_retained means the client is provisioned zero_retention and already had its one chance to read it; cancelled means the job, or the root job it ran for, was cancelled. A cancelled job serves no results (it is not charged, including delivered parts) — not its own progressive values, and not a delegated child's result. It is a read state only, derived on the wire; no row stores it. storage_unavailable withholds a retained result while its workspace binding refuses access; Job.result_error explains the current refusal. A late poll returns the job with a state, never a 404 — "this expired" and "this never existed" are a scheduling problem and a bug respectively, and a 404 makes them identical.

When execution began. Null while still queued.

cancelled is a first-class terminal status, not a failed variant.

Conflating them makes error-rate metrics lie and forces every client to string-match an error code.

Which console history this deep-search job belongs to. deep_search is the public route and the Deep Search page; qa and workbook are the console chat skins over the same agent. It does not pick the implementation. Null for fact-search and every non-deep-search kind. Jobs stored before this field existed echo deep_search. Read from the stored payload, so it rides the same retention path as query.

Measured work in legacy credit units, retained even when a failed or cancelled job is not billed. Kept for compatibility: credits is the authoritative billed amount.

True once credits is final and will not change. False while the job is queued or running, and until any cleanup of its delegated stages has been accounted for. A failed tool job (read_file, run_sql, hybrid_search, grep, file_metadata, folder_metadata) created with an Idempotency-Key stays false for one hour after it fails, because a retry with the same key re-runs it; after that hour it is final and the retry returns the stored error.

When credits became final. Null until usage_final is true.

The workspace this job reads. Null for a document operation whose source is an upload, a URL, or a prior parse result.