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.

      • preview object | null required

        A one-glance preview of a finished developer report, for showing it in a list. Present only on GET /v1/deep-research/jobs, and only for a `developers` item that is done; null everywhere else.

        • name string | null required

          The developer’s display name. Null when they set none.

        • avatarUrl string | null required

          GitHub avatar image URL.

        • summary string | null required

          One sentence about the developer: the first sentence of their LinkedIn headline or GitHub bio. Null when neither exists.

        • tags array of string required

          Plain labels to search and filter a report list on: top languages and city.

        • location string | null required

          The city they work from. Null when unknown.

        • cracked boolean required

          Whether their devRank tier counts as cracked (Elite and above).

        • highlights array of string required

          The report's top signals, as signal names best first (at most three). No percentiles. Empty for a report whose highlights are not stored yet; they fill in on later reads.

        • signals array of string required

          The signals worth a glance, ready to show: what they mostly build, signature technologies, standing, stars, followers.

    • requestedBy string | null required

      The teammate who started the job, by display name. Present only on GET /v1/deep-research/jobs; null for a job started by an API key or by Vamo, and on every other endpoint.

• 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 research: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 research:deep
  • 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.

• 409 The job needs a GitHub connection that is missing or was lost. When none is connected, `reason` is `GITHUB_CONNECTION_REQUIRED` and the body carries `instruction`, a sentence to relay to the member, and can carry `connectUrl`, the link they open to connect one (for an API caller a no-login link, good for 15 minutes and one connection), and `action`: `{ id, kind, url, expiresAt }`, an action finished by the same connection. With no member behind an API key there is no one to connect for, and no `connectUrl`.
  • 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.