---
title: "Start a job"
method: POST
path: "/api/jobs/{namespace}"
tags: ["jobs"]
---

# Start a job

`POST /api/jobs/{namespace}`

## Path parameters

- `namespace` string, required

## Request body

- object
  - `spaceId` string
  - `dockerImage` string
  - `arguments` string[]
  - `command` string[]
  - `environment` object
  - `secrets` object
  - `flavor` 'cpu-basic' | 'cpu-upgrade' | 'cpu-performance' | 'cpu-xl' | 'sprx8' | 'zero-a10g' | 't4-small' | 't4-medium' | 'l4x1' | 'l4x4' | 'l40sx1' | 'l40sx4' | 'l40sx8' | 'a10g-small' | 'a10g-large' | 'a10g-largex2' | 'a10g-largex4' | 'a100-large' | 'a100x4' | 'a100x8' | 'h200' | 'h200x2' | 'h200x4' | 'h200x8' | 'rtx-pro-6000' | 'rtx-pro-6000x2' | 'rtx-pro-6000x4' | 'rtx-pro-6000x8' | 'inf2x6', required
  - `arch` 'amd64' | 'arm64'
  - `timeoutSeconds` integer, nullable
  - `attempts` integer — Max number of attempts to make. For example, if you set this to 3, the job will be retried up to 2 times if it fails.
  - `labels` object — Labels for the job as key-value pairs. Both keys and values must be max 100 characters and contain only alphanumeric characters, dots, dashes, and underscores.
  - `volumes` object[] — HuggingFace Buckets or Repos to mount as volumes in the job container.
    - `type` 'bucket' | 'model' | 'dataset' | 'space', required
    - `source` string, required — Source identifier, e.g. 'username/my-bucket' or 'username/my-model'
    - `mountPath` string, required — Mount path inside the container, e.g. '/data'
    - `revision` string — Git revision (only for repos, defaults to 'main')
    - `readOnly` boolean — Read-only mount (true for repos, false default for buckets)
    - `path` string — Subfolder prefix inside the bucket/repo to mount, e.g. 'path/to/dir'
  - `expose` object — Ports to expose publicly through the jobs proxy. Each port is reachable at `https://<job_id>--<port>.<jobs-public-domain>`. Access requires a HF token with read access to the job's namespace, except for ports also listed in `portsPublic`.
    - `ports` integer[], required
    - `portsPublic` integer[] — Subset of `ports` reachable without any authentication.
  - `ssh` object — When `enabled`, the job's container is reachable over SSH at `ssh <job_id>@ssh.hf.jobs`. Only the job's owner is allowed in, authenticated by an SSH public key registered on the Hub.
    - `enabled` boolean
  - `resourceGroupId` string

## Response `200`

The job after it has been started

- object
  - `id` string, required
  - `createdAt` string, date-time, required
  - `spaceId` string
  - `dockerImage` string
  - `timeout` number
  - `environment` object, required
  - `command` string[]
  - `arguments` string[]
  - `arch` 'amd64' | 'arm64'
  - `flavor` 'cpu-basic' | 'cpu-upgrade' | 'cpu-performance' | 'cpu-xl' | 'sprx8' | 'zero-a10g' | 't4-small' | 't4-medium' | 'l4x1' | 'l4x4' | 'l40sx1' | 'l40sx4' | 'l40sx8' | 'a10g-small' | 'a10g-large' | 'a10g-largex2' | 'a10g-largex4' | 'a100-large' | 'a100x4' | 'a100x8' | 'h200' | 'h200x2' | 'h200x4' | 'h200x8' | 'rtx-pro-6000' | 'rtx-pro-6000x2' | 'rtx-pro-6000x4' | 'rtx-pro-6000x8' | 'inf2x6', required
  - `createdBy` object, required
    - `id` string, required
    - `name` string, required
  - `resourceGroupId` string
  - `retry` number
  - `startedAt` string, date-time
  - `finishedAt` string, date-time
  - `durations` object
    - `schedulingSecs` number
    - `runningSecs` number
    - `totalSecs` number
  - `volumes` object[]
    - `type` string, required
    - `source` string, required
    - `mountPath` string, required
    - `revision` string
    - `readOnly` boolean
    - `path` string
  - `expose` object — Ports exposed through the jobs proxy (see `status.exposeUrls` for the reachable URLs).
    - `ports` integer[], required
    - `portsPublic` integer[] — Subset of `ports` reachable without any authentication.
  - `type` 'job', required
  - `owner` object, required
    - `id` string, required
    - `name` string, required
    - `type` 'user' | 'org', required
    - `avatarUrl` string, required
  - `resourceGroup` object
    - `id` string, required
    - `name` string, required
    - `numUsers` number
  - `initiator` union
    - object
      - `id` string, required
      - `name` string, required
      - `type` 'user' | 'org', required
      - `avatarUrl` string, required
    - object
      - `type` 'scheduled-job', required
      - `id` string, required
    - object
      - `type` 'duplicated-job', required
      - `id` string, required
    - object
      - `type` 'webhook', required
      - `id` string, required
  - `status` object, required
    - `stage` 'COMPLETED' | 'CANCELED' | 'ERROR' | 'DELETED' | 'RUNNING' | 'SCHEDULING', required
    - `message` string, nullable, required
    - `cancelReason` union
      - 'NO_CREDITS' | 'NO_SUBSCRIPTION'
      - string
    - `failureCount` number
    - `exposeUrls` string[] — One reachable URL per port declared in `expose.ports`, in the same order (e.g. `https://<job_id>--8000.hf.jobs`). Absent when the job is not exposed.
    - `sshUrl` string — SSH endpoint for the job (e.g. `ssh://<job_id>@ssh.hf.jobs`). Only present when `ssh.enabled`.
  - `secrets` string[]
  - `labels` object
  - `hfToken` object
    - `ownerName` string, required
    - `orgName` string
    - `tokenRole` 'read' | 'write' | 'fineGrained'
    - `tokenId` string
    - `settingsUrl` string

---

[API](https://skmtc.net/huggingface/apis/hub-api-endpoints.md) · [All operations](https://skmtc.net/huggingface/apis/hub-api-endpoints/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/huggingface/hub-api-endpoints/versions/6ab9f7d9cfb5/schema)