GET /v1/search/jobs

List the account’s deep-search jobs

Access

Authenticated (self)

Cost

Free

Rate limit

120 / minute per account

Quota

None

The deep-search history for the account, newest first. Pass savedSearchId to scope to the rounds run for one saved search. Self-scoped and free.

Query parameters

savedSearchId string

max 16 chars

Responses

200 The job history
- jobs array of object required
  
  The account’s deep-search jobs, newest first.
  
  max 5000 items
  - 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.
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.