Run: Jobs

The Run Jobs endpoints expose async background work for the run service. Use POST /api/v1/run/search/jobs to queue a candidate search and receive a job handle, then poll that handle through GET /api/v1/run/jobs/{job_id}. The status endpoint supports long-polling via wait=done so callers can block until the job completes or a timeout is reached.

Start an async search job

Queue a candidate search in the background and return a job handle that can be polled through the jobs endpoint.

`POST /api/v1/run/search/jobs`

This endpoint takes no parameters.

Request Body

The request body is a run_Selector object describing the search query.

cURL
TypeScript SDK

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

Responses

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "kind": "search-resolve",
  "status": "queued",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

{
  "error": "missing app",
  "code": 400
}

{
  "error": "job queue is full",
  "code": 503
}

Get job status

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.

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

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)

cURL
TypeScript SDK

curl -X GET 'https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com/api/v1/run/jobs/550e8400-e29b-41d4-a716-446655440000?wait=done&timeout_ms=30000' \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

const { data: status } = await client.run.jobs.getJobStatus("550e8400-e29b-41d4-a716-446655440000", { wait: "done", timeout_ms: 30000 });

Responses

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

{
  "error": "job not found",
  "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`