App: Jobs

Overview

The Jobs API lets you queue long-running app operations as background jobs and poll their status. Use these endpoints when a synchronous request would time out — start a search job, receive a job handle, then poll the status endpoint until the job reaches a terminal state. The status endpoint also supports long-polling to block until completion.

Get job status

GET /api/v1/run/jobs/{job_id}

Retrieve the current status of an async background job. Supports long-polling with wait=done to block until the job completes or a timeout is reached.

Parameters

Name	In	Type	Required	Description
`job_id`	path	string	Yes	Job identifier (UUID)
`wait`	query	string	No	Set to `done` to long-poll until job completes
`timeout_ms`	query	integer	No	Long-poll timeout in milliseconds (default `0`, max `120000`)

Response

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "kind": "source-sync",
  "status": "done",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:05Z",
  "result_type": "search-response",
  "result": {
    "candidates": []
  }
}

{
  "error": "No job exists with the requested identifier",
  "code": 404
}

Error Code	Title	Description	Resolution
`JOB_NOT_FOUND`	Job not found	No job exists with the requested identifier	Use the job_id returned by syncSource or syncAllSources

SDK Usage

const job = await client.app.jobs.getStatus({
  job_id: "550e8400-e29b-41d4-a716-446655440000",
  wait: "done",
  timeout_ms: 30000
});

cURL

curl https://api.hoody.com/api/v1/run/jobs/550e8400-e29b-41d4-a716-446655440000?wait=done&timeout_ms=30000 \
  -H "Authorization: Bearer <token>"

Start an async search job

POST /api/v1/run/search/jobs

Queue a candidate search in the background and return a job handle that can be polled through the Get job status endpoint. The response is returned immediately with HTTP 202 Accepted and a job_id you can poll.

Request Body

The request body is a Selector object describing the search criteria. The full selector schema is shared with the synchronous run endpoint; the only field always required is app.

{
  "app": "firefox",
  "os": "linux",
  "kind": "gui",
  "limit": 25
}

Response

{
  "job_id": "9b2c1f4a-7d3e-4a8b-bf6e-2c1a9d8e7f01",
  "kind": "search-resolve",
  "status": "queued",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

{
  "error": "Invalid selector: app is required",
  "code": 400
}

{
  "error": "Job queue unavailable",
  "code": 503
}

SDK Usage

const job = await client.app.jobs.createSearch({
  data: {
    app: "firefox",
    os: "linux",
    kind: "gui"
  }
});

const status = await client.app.jobs.getStatus({
  job_id: job.job_id,
  wait: "done",
  timeout_ms: 60000
});

cURL

curl -X POST https://api.hoody.com/api/v1/run/search/jobs \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "firefox",
    "os": "linux",
    "kind": "gui"
  }'