GET /v1/deep-research/jobs/{id}

Poll a deep-research job

Access

Authenticated (self)

Cost

Free

Rate limit

120 / minute per account

Quota

None

The job, its elapsed time, and every subject with its current stage. Polling also DRIVES the job: each read advances the next round and stops any subject whose runner died, so a job can never sit in a stage with nothing happening and no explanation. Self-scoped and free.

Path parameters

id string required

max 16 chars

Responses

200 The job
- job DeepResearchJob required
  
  The job and its per-developer items.
  - id string required
    
    The job id. Poll it for progress.
  - subject string required
    
    What kind of thing this job researches.
    
    developers
  - status string required
    
    Where the job stands overall. Individual subjects settle independently; read `items` for the detail.
    
    runningsucceededpartialfailed
  - createdAt string required
    
    When the job was submitted, as an ISO 8601 instant.
  - finishedAt string | null required
    
    When the job reached a terminal state, as an ISO 8601 instant. Null while running.
  - elapsedMs integer required
    
    Time so far while running, and total time once finished, in milliseconds. Computed server-side, so it does not depend on your clock.
    
    min 0
  - requestedCount integer required
    
    How many developers you asked for. NOT what you pay: see `deliveredCount`.
    
    min 0
  - deliveredCount integer required
    
    How many developers actually landed a report. This is the billable count: a developer that failed is never billed.
    
    min 0
  - items array of DeepResearchItem required
    
    Per-developer state, including the reason for each one that did not land.
    
    login string required
    
    The GitHub handle this item researches.
    
    status string required
    
    Where this one subject stands. Items settle independently: partial success across a job is normal.
    
    pendingrunningdonefailed
    
    failCode string | null required
    
    Machine-readable failure reason. Null while the item can still succeed or has succeeded. Branch on this, not on `failMessage`.
    
    not_foundrate_limitedprovider_errortimeoutabandonedengine_error
    
    failMessage string | null required
    
    The failure explained in words you can show a user, including what to do about it. Null while the item can still succeed.
    
    source string | null required
    
    Whether the delivered answer was researched fresh or served from a recent previous run. Both are billed the same, because the answer is what you are buying, but a cached answer must not be presented as fresh. Null until an answer lands.
    
    freshcache
    
    reportPath string | null required
    
    The API path to read this developer’s report. Null until one exists.
    
    startedAt string | null required
    
    When this item started, as an ISO 8601 instant. Null while queued.
    
    finishedAt string | null required
    
    When this item settled, as an ISO 8601 instant. Null until it does.
401 No or invalid credential
- code string required
  
  Stable machine-readable error code. Branch on this, never on the numeric status.
  
  bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
- message string required
  
  Human-readable explanation of the refusal.
- status integer required
  
  The HTTP status code, repeated in the body.
- remedy object
  
  A self-serve path forward, when one exists (a 402 points at the credit top-up).
  - kind string required
    
    What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.
    
    topupconnect_mailbox
  - url string required
    
    Where to go to clear the condition: an API path, or a web app page when only a person can.
404 No such deep-research job in this account
- code string required
  
  Stable machine-readable error code. Branch on this, never on the numeric status.
  
  bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
- message string required
  
  Human-readable explanation of the refusal.
- status integer required
  
  The HTTP status code, repeated in the body.
- remedy object
  
  A self-serve path forward, when one exists (a 402 points at the credit top-up).
  - kind string required
    
    What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.
    
    topupconnect_mailbox
  - url string required
    
    Where to go to clear the condition: an API path, or a web app page when only a person can.