# App: Jobs

**Page:** api/app/jobs

[Download Raw Markdown](./api/app/jobs.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## 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




```json
{
  "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": []
  }
}
```




```json
{
  "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

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

### cURL

```bash
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](/api/app/jobs/#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`.

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

### Response




```json
{
  "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"
}
```




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




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




### SDK Usage

```ts
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

```bash
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"
  }'
```


Combine `createSearch` with `getStatus({ wait: "done" })` to mimic a synchronous call while still offloading long-running lookups to the background worker. Set `timeout_ms` up to `120000` to control how long the long-poll blocks before returning the current state.