---
title: Job
sidebar_label: Job
sidebar_position: 1
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lium.io/llms.txt
> Use this file to discover all available pages before exploring further.

<!-- Generated by scripts/generate_sdk_reference.py. Do not edit directly. -->

# Job

```python
from lium.sdk import Job
```

Defined in `lium.sdk.jobs`.

A command started in the background on a pod.

Returned by [`run_background()`](/developers/sdk/reference/client/lium#run_background) and [`job()`](/developers/sdk/reference/client/lium#job). Every method
opens one short SSH session; nothing is cached, so the answers reflect the
pod as it is now.

```python
Job(
    client: lium.sdk.client.Lium,
    pod: lium.sdk.models.PodInfo,
    *,
    name: str,
    pid: int,
    command: str,
    job_dir: str = '/workspace/logs'
)
```

## Attributes

| Name | Type | Description |
| --- | --- | --- |
| `pod` |  |  |
| `name` |  |  |
| `pid` |  |  |
| `command` |  |  |
| `job_dir` |  |  |
| `log_path` |  |  |
| `pid_file` |  |  |
| `id_file` |  |  |
| `exit_file` |  |  |
| `cmd_file` |  |  |

## Methods

| Method | Description |
| --- | --- |
| [`to_dict`](#to_dict) |  |
| [`status`](#status) | \{"state": "running" \| "exited" \| "gone", "exitcode": int \| None\}. |
| [`is_running`](#is_running) |  |
| [`poll`](#poll) | None while the job runs, its exit code once it ended (subprocess.Popen.poll semantics). |
| [`wait`](#wait) | Block until the job ends and return its exit code. |
| [`wait_for_port`](#wait_for_port) | Block until TCP port accepts connections inside the pod. |
| [`logs`](#logs) | The job's combined stdout/stderr; the last tail lines when given. Empty if no log yet. |
| [`kill`](#kill) | Send signal to the job's whole process group. Returns whether anything received it. |

### to_dict

```python
def to_dict() -> Dict[str, Any]:
```

### status

```python
def status() -> Dict[str, Any]:
```

``\{"state": "running" | "exited" | "gone", "exit_code": int | None\}``.

``gone`` means the process is not alive and left no exit code — killed as
a group, or the pod restarted underneath it (a PID that another process
took after the restart does not count as alive: the ``.id`` file decides).
A job with no ``.id`` file (started before the file existed) is ``gone`` too.

### is_running

```python
def is_running() -> bool:
```

### poll

```python
def poll() -> Optional[int]:
```

``None`` while the job runs, its exit code once it ended (``subprocess.Popen.poll`` semantics).

**Raises:**
 - **LiumError:**  the process is gone without an exit code.

### wait

```python
def wait(timeout: Optional[float] = None, *, poll_interval: float = 5) -> int:
```

Block until the job ends and return its exit code.

**Raises:**
 - **TimeoutError:**  still running after ``timeout`` seconds (the job keeps running).
 - **LiumError:**  the process vanished without writing an exit code.

### wait_for_port

```python
def wait_for_port(
    port: int,
    timeout: float = 600,
    *,
    host: str = '127.0.0.1',
    poll_interval: float = 3
) -> None:
```

Block until TCP ``port`` accepts connections inside the pod.

The probe and the job's liveness are read in the same SSH round trip, and
the job's state is judged first: a server that crashed while loading fails
this call at once with its exit code and the last log lines, even when
another process holds the port. A
job that exited 0 with the port open counts as ready (it forked its
server and left).

**Raises:**
 - **LiumError:**  the job ended (or vanished) before the port answered.
 - **TimeoutError:**  the port did not answer within ``timeout`` seconds.

### logs

```python
def logs(tail: Optional[int] = None) -> str:
```

The job's combined stdout/stderr; the last ``tail`` lines when given. Empty if no log yet.

### kill

```python
def kill(signal: str = 'TERM') -> bool:
```

Send ``signal`` to the job's whole process group. Returns whether anything received it.

Nothing is signaled when the PID belongs to a different process (the pod
restarted and that process took the number) or when the job has no
``.id`` file to check it against; the call returns ``False``.