Run: Jobs

Create async background jobs for candidate searches and poll their status. Use these endpoints when a search or sync operation may take longer than a synchronous request can wait — submit a job, receive a handle, then poll until completion.

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 jobs endpoint.

This endpoint takes no parameters.

Request Body

The body is a run_Selector object describing the candidate search. Only app is required; the remaining fields narrow or shape the result.

{
  "app": "firefox",
  "os": "linux",
  "kind": "gui",
  "source": ["nix", "appimage"],
  "limit": 25,
  "pick": "first"
}

Response

{
  "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 unavailable",
  "code": 503
}

SDK usage

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

console.log(job.job_id);

cURL

curl -X POST "https://proj-abc123-cont-xyz789-run-1.us-east-1.containers.hoody.icu/api/v1/run/search/jobs" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "firefox",
    "os": "linux",
    "kind": "gui"
  }'

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": "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": "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

// Simple poll
const { data: status } = await client.run.jobs.getJobStatus(
  "550e8400-e29b-41d4-a716-446655440000"
);

// Long-poll until the job completes (or 30s timeout)
const { data: done } = await client.run.jobs.getJobStatus(
  "550e8400-e29b-41d4-a716-446655440000",
  { wait: "done", timeout_ms: 30000 }
);

cURL

curl "https://proj-abc123-cont-xyz789-run-1.us-east-1.containers.hoody.icu/api/v1/run/jobs/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <token>"

# Long-poll until the job completes or 30s elapses
curl "https://proj-abc123-cont-xyz789-run-1.us-east-1.containers.hoody.icu/api/v1/run/jobs/550e8400-e29b-41d4-a716-446655440000?wait=done&timeout_ms=30000" \
  -H "Authorization: Bearer <token>"