Are you a cracked engineer? See your Vamo profile
vamo

Start deep research

POST https://api.vamotalent.ai/v2/deep-research/jobs
Access
Authenticated
research:deep
Cost
Free
Rate limit
6 / minute per account
Quota
deep_research

Starts a deep-research job and answers at once with the job and checkBackSeconds. Nothing is researched while you wait on this call. subject: "developers" researches GitHub handles (logins); subject: "repos" researches owner/name repositories (repos): who builds each one and who stars it. subject: "rank" scores up to 50 GitHub handles (logins) against a question you write, 0 to 100 each with a one-line reason, and returns them best first in ranking. Then read GET /v2/deep-research/jobs/{id} every checkBackSeconds until status is no longer running; that read carries each finished report. Partial success is normal: each subject that did not land says why in failCode and failMessage, and is not billed. A job can need a GitHub account connected by the member you act for (an API key acts as the member who created it). When it does and none is connected, the call answers 409 with reason: GITHUB_CONNECTION_REQUIRED, an instruction to relay to the person and, when there is one, a connectUrl they open to connect it. Send the same request again once they have.

Request body CreateDeepResearchJobRequest application/json

Option 1
  • subject string required

    Research developers. The field is a closed vocabulary so more subjects can be added without changing the job contract.

    developers
  • logins array of string required

    The GitHub handles to research, up to 25 per job. They are processed in rounds behind the job, not all at once.

    min 1 items, max 25 items
  • force boolean

    Re-research a subject even when a recent report exists. Costs the same either way, so use this only when you specifically need fresher data.

  • githubConnectionId string

    Ignored when calling with an API key (that path draws from your GitHub connection pool automatically). Only relevant for a signed-in dashboard member: the id of one of your linked GitHub connections (GET /v1/me/github), required in that case so the job runs on your own GitHub quota.

    max 16 chars
Option 2
  • subject string required

    Research repositories: who builds each one (recency-weighted contributors), who validates it (recent starrers plus where the repo’s star audience places), and identity facts on both.

    repos
  • repos array of string required

    The repositories to research as `owner/name` references, up to 25 per job. They are processed in rounds behind the job, not all at once.

    min 1 items, max 25 items
  • force boolean

    Re-research a subject even when a recent report exists. Costs the same either way, so use this only when you specifically need fresher data.

  • githubConnectionId string

    Ignored when calling with an API key (that path draws from your GitHub connection pool automatically). Only relevant for a signed-in dashboard member: the id of one of your linked GitHub connections (GET /v1/me/github), required in that case so the job runs on your own GitHub quota.

    max 16 chars
Option 3
  • subject string required

    Rank developers against a question: each one is scored 0 to 100 on how well their public work answers it, with a one-line reason, and the job returns them best first.

    rank
  • question string required

    What you are looking for, in words, up to 4000 characters: the role, the work, the stack. Name a company here if it matters; there is no separate field for one.

    max 4000 chars
  • logins array of string required

    The GitHub usernames to score, up to 50 per job. Repeats (in any case) are scored once.

    min 1 items, max 50 items
  • githubConnectionId string

    Ignored when calling with an API key (that path draws from your GitHub connection pool automatically). Only relevant for a signed-in dashboard member: the id of one of your linked GitHub connections (GET /v1/me/github), required in that case so the job runs on your own GitHub quota.

    max 16 chars

Responses

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.

      developersreposrank
    • status string required

      Where the job stands overall. Individual subjects settle independently; read `items` for the detail.

      runningsucceededpartialfailed
    • checkBackSeconds integer

      While the job is running: how many seconds to wait before reading it again. Absent once the job has finished.

    • 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 reused answer should 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.

      • fit DeepResearchFit required

        A `rank` job only: this developer’s fit to the question, once they were scored. Null on every other subject, while they wait, and for a developer who could not be scored (see `failCode`).

        • score integer required

          How well this developer answers the question, 0 to 100. Absolute, not relative to the list: 80 means the same on every list, so a list of similar people can score close together.

          min 0, max 100
        • tier string required

          `strong` at 70 and above, `adjacent` from 40 to 69, `off` below 40. Derived from the score.

          strongadjacentoff
        • reason string required

          One line on why: a fact Vamo wrote from their public work (a repo and its counts), which the model picked as the best evidence. Never written by a model.

        • rank integer required

          Their place in the ranking, 1 first. Equal scores share a place (1, 2, 2, 4).

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

    • ranking DeepResearchRanking required

      A `rank` job only, once it has finished with at least one developer scored (`succeeded` or `partial`): the question and the scored developers, best first. Null on every other subject, while the job runs, and when nobody could be scored.

      • question string required

        The question the developers were scored against.

      • model string required

        The model that scored them.

      • promptVersion string required

        The version of Vamo’s scoring prompt. Scores from different versions are not compared.

      • people array of DeepResearchRankedPerson required

        Every developer who was scored, best first: score, then the depth of their work, then the order you sent them in. A developer who could not be scored is not here; their item says why.

        • login string required

          Their GitHub username, as you sent it.

        • id string | null required

          Their Vamo developer id, the one every other developer endpoint takes (enrich, the contribution garden, deep research). Resolved from the login when they were scored. Null on rankings made before ids were kept.

        • name string | null required

          Their display name. Null when they set none.

        • title string | null required

          Their current title. Null when unknown.

        • company string | null required

          Where they work now. Null when unknown.

        • location string | null required

          Where they are. Null when unknown.

        • avatarUrl string | null required

          GitHub avatar image URL.

        • githubUrl string required

          Their GitHub profile.

        • linkedinUrl string | null required

          Their LinkedIn profile. Null when unknown.

        • fit object required
          • score integer required

            How well this developer answers the question, 0 to 100. Absolute, not relative to the list: 80 means the same on every list, so a list of similar people can score close together.

            min 0, max 100
          • tier string required

            `strong` at 70 and above, `adjacent` from 40 to 69, `off` below 40. Derived from the score.

            strongadjacentoff
          • reason string required

            One line on why: a fact Vamo wrote from their public work (a repo and its counts), which the model picked as the best evidence. Never written by a model.

          • rank integer required

            Their place in the ranking, 1 first. Equal scores share a place (1, 2, 2, 4).

    • credits object | null required

      A `rank` job only: what it was charged, on the model tokens it actually used. Null on other subjects, which are billed per delivered subject.

      • charged integer | null required

        Credits this job was charged, once settled. Null until then.

        min 0
vamo

© 2026 Vamo Holdings, Inc.