# Run: Jobs

**Page:** api/run/jobs

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

---

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



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

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

### Response



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


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


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



### SDK usage

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

console.log(job.job_id);
```

### cURL

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



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


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

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

```bash
# 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>"
```


When polling repeatedly, prefer the `wait=done` long-poll form over tight client-side loops. The server holds the connection open until the job reaches a terminal state, which reduces request volume and surfaces the result faster.