Start a deep-research job on up to 25 subjects (developers or repositories)

Request body CreateDeepResearchJobRequest

Responses

• 202 The job, with every subject pending
  • job DeepResearchJob required

    The job and its per-developer items.

    • id string required

      The job id. Poll it for progress.

    • name string | null required

      A short label generated from the developers the job was started with, for showing the job in a list. Null on jobs created before naming existed: fall back to the created time.

    • subject string required

      What kind of thing this job researches.

      developersrepos
    • 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 all necessarily land a report: see `deliveredCount`.

      min 0
    • deliveredCount integer required

      How many developers actually landed a report. A developer whose research failed is not counted here.

      min 0
    • items array of DeepResearchItem required

      Per-developer state, including the reason for each one that did not land.

      • login string required

        The subject reference this item researches: a GitHub handle for the `developers` subject, an `owner/name` for `repos`. The field name predates the second subject; `subjectRef` is the same value under its honest name.

      • subjectRef string required

        The subject reference, same value as `login`: a GitHub handle for `developers`, an `owner/name` for `repos`.

      • 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. The two are equivalent in content, 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 subject’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_errorbuild_failed
  • 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 how to restore access).

    • 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.

• 402 Plan lacks search:deep, or insufficient balance
  • 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_errorbuild_failed
  • 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 how to restore access).

    • 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.

• 403 Missing search:deep (role)
  • 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_errorbuild_failed
  • 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 how to restore access).

    • 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.

• 429 Submit rate limit or the deep-research quota is exhausted
  • 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_errorbuild_failed
  • 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 how to restore access).

    • 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.