get_job
Read-only
Poll an async job: status, real engine stage, progress, ETA, result/error.
Poll after poll_after_seconds until status is "succeeded" (result holds the full
generate body) or "failed" (error holds the typed envelope). Only the owning
account can read a job; a foreign/unknown id is not_found (no existence leak).
Returns {job_id, status, stage, progress_pct, eta_seconds, elapsed_ms,
poll_after_seconds, result, error}. Errors: unauthorized, not_found, rate_limited.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | The job's id, as returned by start_generate_job (or by a generate_hooks call that auto-jobbed on deadline_ms). Account-scoped: an id you do not own reads as not_found. | |
| api_key | No | API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (the stdio default). No key resolvable -> unauthorized. | |
| result_view | No | Use compact for source evidence and costs with less response text. Full preserves every audit receipt. Views never rerun or recharge research. | full |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | On failure: the same typed error envelope a synchronous call returns. details.cancelled true means YOU cancelled it with cancel_job, not a fault. | |
| stage | No | The real engine stage while running (e.g. brief, draft, judge). | |
| job_id | No | The job polled. | |
| result | No | On success: the FULL generate (or batch) body, always full-verbosity. At standard/full, a judge-ranked smart hook may also carry {shape, phone_test, say_it}; a judge-ranked research hook carries receipts {persona, shape, phone_test, say_it, pattern_source}. pattern_source is null when no measured opener was attributed, otherwise its nested provenance is the authoritative actual platform, source surface, transcript method, language, route, media, and origin-time record. Minimal keeps persona and shape, plus phone_test only when it is the warning value 'fail'. result_view=compact projects V1 research to source evidence, citations, limitations, cost and an execution summary. Full is the compatible default; changing views never executes research again. Other job types retain their existing body. | |
| status | No | queued (waiting on a worker), running, recovery_required (a hook-research V2 job fenced on ambiguous vendor settlement; operator recovery owns it), succeeded (see `result`), failed (see `error`). Stop polling on the last two. | |
| elapsed_ms | No | Milliseconds since the job started running. | |
| eta_seconds | No | Estimated seconds remaining. | |
| progress_pct | No | 0-100 progress within the run. | |
| hook_instances | No | Immutable non-prose served-occurrence identities. Profile-bound queued/running work returns an empty list; a successful result returns one row per served hook. | |
| poll_after_seconds | No | How long to wait before polling again. | |
| resolved_creator_profile | No | Exact immutable creator-profile binding used by this occurrence. Null/absent for inline or unprofiled generation. |