# `HuggingfaceClient.Hub.Jobs`
[🔗](https://github.com/huggingface/huggingface_client/blob/v0.1.0/lib/huggingface_client/hub/jobs.ex#L1)

HuggingFace Hub Inference Jobs API.

Jobs let you run arbitrary Docker containers or HF Spaces as serverless
compute tasks. Billing is per-second based on the `flavor` (hardware tier).

## Usage

    {:ok, job} = HuggingfaceClient.Hub.Jobs.run("my-org",
      docker_image: "pytorch/pytorch:2.3.0-cuda12.1-cudnn8-runtime",
      flavor:       "gpu-t4-medium",
      command:      ["python", "train.py"],
      env:          %{"EPOCHS" => "10"},
      access_token: System.get_env("HF_TOKEN")
    )

    # Poll until done
    {:ok, result} = HuggingfaceClient.Hub.Jobs.wait(job["id"],
      access_token: System.get_env("HF_TOKEN")
    )

# `cancel`

```elixir
@spec cancel(String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Exception.t()}
```

Cancels a running job.

# `get`

```elixir
@spec get(String.t(), String.t(), keyword()) :: {:ok, map()} | {:error, Exception.t()}
```

Fetches the current status of a job by `job_id`.

# `list`

```elixir
@spec list(
  String.t(),
  keyword()
) :: {:ok, list()} | {:error, Exception.t()}
```

Lists all jobs under `namespace`.

# `list_flavors`

```elixir
@spec list_flavors(keyword()) :: {:ok, list()} | {:error, Exception.t()}
```

Returns the available hardware flavors for running jobs.

# `run`

```elixir
@spec run(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, Exception.t()}
```

Submits a new inference job under `namespace` (user or org slug).

## Required option (one of):

- `:docker_image` — Docker image to run (e.g. `"pytorch/pytorch:latest"`)
- `:space_id`     — HF Space to run as a job (e.g. `"my-org/my-space"`)

## Optional options

- `:flavor`         — hardware tier: `"cpu-basic"`, `"gpu-t4-medium"`, etc.
- `:command`        — override default command, list of strings
- `:env`            — map of environment variables
- `:secrets`        — map of secret names to values
- `:timeout`        — max runtime seconds
- `:access_token`

# `wait`

```elixir
@spec wait(String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Exception.t()}
```

Polls a job until it reaches a terminal state (`"completed"` or `"failed"`).

Returns `{:ok, job_map}` when done or `{:error, reason}` on timeout/failure.

## Options

- `:timeout_s`  — max total wait in seconds (default: 600)
- `:interval_ms` — polling interval ms (default: 5_000)
- `:namespace`  — job namespace (required unless included in `job_id`)
- `:access_token`

---

*Consult [api-reference.md](api-reference.md) for complete listing*