GET /v1/search/jobs/{id}

Poll a deep-search job

Access

Authenticated (self)

Cost

Free

Rate limit

120 / minute per account

Quota

None

The job’s status, live progress meter, per-round delivered/banked history, and the durable delivered result set (the ranked developers, oldest round first). Self-scoped and free — poll as often as you like.

Path parameters

id string required

max 17 chars

Responses

200 The job detail
- job object required
  - id string required
    
    The job id. Poll `GET /v1/search/jobs/{id}` with it.
  - status string required
    
    Where the job stands. A job is still working until it reaches a terminal status; poll rather than assuming a submit returned everything.
    
    queuedrunningsucceededpartialfailedcanceled
  - targetCount integer required
    
    How many developers you asked this job to find.
  - targetMode string required
    
    `exact` = deliver the target count or report a clean partial. `best_effort` = deliver what the lane can find. Either way an under-delivery is reported as a partial, never padded.
    
    exactbest_effort
  - savedSearchId string | null required
    
    The saved search this job belongs to, when it was run from one. Delivered-once uniqueness is enforced across the saved search, so a later job will not repeat developers an earlier one delivered.
  - projectId string | null required
    
    The project this job was run for, when one was named.
  - progress SearchJobProgress required
    
    Counts so far. Null before the first round has produced anything.
    
    delivered integer required
    
    How many developers this job has actually handed you so far, across all rounds. This is what you received, NOT what you paid for.
    
    min 0
    
    banked integer required
    
    Developers found and held back beyond the current target, ready to be handed over by a `/more` round without re-running the search.
    
    min 0
    
    round integer required
    
    How many rounds this job has run. Round 0 is the agentic sweep; later rounds page deterministically.
    
    min 0
    
    considered integer required
    
    How many candidates this job was BILLED on: the ones the agent enriched and put in front of the recruiter judge, most of which are rejected before you ever see them. This is normally several times `delivered`, and the ratio between the two is what you paid for. On a round that fell back to the deterministic pager, billing is per developer delivered and this equals `delivered`.
    
    min 0
  - error string | null required
    
    Why a failed job failed, in plain words. Null on every job that ended well.
  - creditsEstimated integer required
    
    The estimate made when the job was submitted. Nothing is charged at submit.
  - creditsCharged integer required
    
    Credits actually charged so far. Settled as rounds complete, on candidates considered rather than delivered.
  - budgetCredits integer | null required
    
    The ceiling you set on what this job may cost, in total, across every round. Null when you set none.
  - budgetRemaining integer | null required
    
    `budgetCredits` minus `creditsCharged`: what is still spendable on this job. A `/more` round is truncated to what this buys, and refused with a 402 once it reaches 0. Refunds put credits back here, because it is derived rather than stored. Null when no ceiling was set.
  - createdAt string required
    
    When the job was submitted, as an ISO 8601 instant.
  - updatedAt string required
    
    When the job last changed, as an ISO 8601 instant.
- rounds array of SearchJobRound required
  
  Per-round delivered/banked history, oldest first.
  
  max 200 items
  - round integer required
    
    The round number. Round 0 is the agentic sweep.
    
    min 0
  - delivered integer required
    
    Developers handed over in this round.
    
    min 0
  - banked integer required
    
    Developers found in this round but held back for a later `/more` round.
    
    min 0
- results array of SearchJobResult required
  
  The durable result set: every developer this job has ranked, delivered or banked, oldest round first. Rows carry ids only; hydrate profiles with `GET /v1/developers/{id}`.
  
  max 5000 items
  - developerId string required
    
    The developer this row refers to. Hydrate the profile with `GET /v1/developers/{id}`.
  - round integer required
    
    The round that produced this row.
    
    min 0
  - rank integer required
    
    Position within its round, best first. Ranks are per round, so they repeat across rounds.
  - score number | null required
    
    The ordering key within this round, descending. Comparable only within the round, and not a statement of match quality. Null when the producing lane did not score.
  - source string required
    
    Which lane produced this row: the agentic selector, or the deterministic pager it falls back to when the agent host is unreachable.
    
    repo_fanoutuser_entityinterestslinkedinbankedagent_select
  - delivered boolean required
    
    True when this developer was handed to you. False means banked: found and held for a later `/more` round.
  - why SearchJobResultWhy required
    
    Why the agent selected this developer for THIS role, in its own words. Present on rows the agentic selector produced (the judgment you paid for); null on rows the deterministic pager produced, which does not reason about candidates.
    
    summary string | null required
    
    One sentence on why this developer fits THIS role, in the judge’s own words.
    
    max 5000 chars
    
    claims array of string required
    
    The supporting statements behind `summary`: the angle they came in on, the fit blurb, and the tags.
    
    max 8 items
    
    repo object | null required
    
    The ONE repository the judge picked as relevant to this role. Not their most-starred repo — that is a popularity artifact. Null when the judge found no role-relevant repo.
    
    fullName string required
    
    GitHub `owner/name`.
    
    max 200 chars
    
    url string required
    
    The public github.com URL of the repository.
    
    max 2048 chars
    
    repoSummary string | null required
    
    A plain-English sentence about `repo`, written for a human to read or paste.
    
    max 5000 chars
  - feedback string | null required
    
    The thumbs verdict you recorded on this developer for this job, if any. Null when none.
    
    updown
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 search 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.