Hugging Face Transformers jobs API
The following endpoints manage jobs.
Documentation
Documentation
https://huggingface.co/docs/huggingface_hub/index
APIReference
https://huggingface.co/docs/hub/api
OpenAPI Specification
openapi: 3.1.0
info:
title: Hub API Endpoints agentic-provisioning jobs API
version: 0.0.1
description: 'We have open endpoints that you can use to retrieve information from the Hub as well as perform certain actions such as creating model, dataset or Space repos. We offer a wrapper Python client, [`huggingface_hub`](https://github.com/huggingface/huggingface_hub), and a JS client, [`huggingface.js`](https://github.com/huggingface/huggingface.js), that allow easy access to these endpoints. We also provide [webhooks](https://huggingface.co/docs/hub/webhooks) to receive real-time incremental info about repos. Enjoy!
The base URL for those endpoints below is `https://huggingface.co`. For example, to construct the `/api/models` call below, one can call the URL [https://huggingface.co/api/models](https://huggingface.co/api/models).
If you''re an Agent, you might prefer the [markdown version OpenAPI spec](https://huggingface.co/.well-known/openapi.md).
'
servers:
- url: https://huggingface.co
description: Hub
security:
- bearerAuth: []
tags:
- name: jobs
x-displayName: Jobs
description: The following endpoints manage jobs.
paths:
/api/jobs/hardware:
get:
description: Get available job hardware
summary: Get job hardware
tags:
- jobs
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: array
items:
type: object
properties:
name:
type: string
prettyName:
type: string
cpu:
type: string
ram:
type: string
ephemeralStorage:
type: string
accelerator:
anyOf:
- type: object
properties:
type:
enum:
- gpu
- neuron
model:
type: string
quantity:
type: string
vram:
type: string
manufacturer:
enum:
- Nvidia
- AWS
required:
- type
- model
- quantity
- vram
- manufacturer
additionalProperties: false
- type: 'null'
unitCostMicroUSD:
type: number
unitCostUSD:
type: number
unitLabel:
type: string
required:
- name
- prettyName
- cpu
- ram
- ephemeralStorage
- accelerator
- unitCostMicroUSD
- unitCostUSD
- unitLabel
additionalProperties: false
description: Available job hardware (public only)
/api/jobs/{namespace}:
get:
description: List of jobs for an entity
summary: List jobs
tags:
- jobs
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: array
items:
type: object
properties:
id:
type: string
createdAt:
type: string
format: date-time
pattern: ^((\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-((0[13578]|1[02])-(0[1-9]|[12]\d|3[01])|(0[469]|11)-(0[1-9]|[12]\d|30)|(02)-(0[1-9]|1\d|2[0-8])))T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z)$
spaceId:
type: string
dockerImage:
type: string
timeout:
type: number
environment:
type: object
propertyNames:
type: string
additionalProperties:
type: string
command:
type: array
items:
type: string
arguments:
type: array
items:
type: string
arch:
enum:
- amd64
- arm64
flavor:
enum:
- 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
createdBy:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
additionalProperties: false
retry:
type: number
startedAt:
type: string
format: date-time
pattern: ^((\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-((0[13578]|1[02])-(0[1-9]|[12]\d|3[01])|(0[469]|11)-(0[1-9]|[12]\d|30)|(02)-(0[1-9]|1\d|2[0-8])))T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z)$
finishedAt:
type: string
format: date-time
pattern: ^((\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-((0[13578]|1[02])-(0[1-9]|[12]\d|3[01])|(0[469]|11)-(0[1-9]|[12]\d|30)|(02)-(0[1-9]|1\d|2[0-8])))T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z)$
durations:
type: object
properties:
schedulingSecs:
type: number
runningSecs:
type: number
totalSecs:
type: number
additionalProperties: false
volumes:
type: array
items:
type: object
properties:
type:
type: string
source:
type: string
mountPath:
type: string
revision:
type: string
readOnly:
type: boolean
path:
type: string
required:
- type
- source
- mountPath
additionalProperties: false
type:
const: job
owner:
type: object
properties:
id:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
name:
type: string
type:
enum:
- user
- org
avatarUrl:
type: string
required:
- id
- name
- type
- avatarUrl
additionalProperties: false
initiator:
anyOf:
- type: object
properties:
id:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
name:
type: string
type:
enum:
- user
- org
avatarUrl:
type: string
required:
- id
- name
- type
- avatarUrl
additionalProperties: false
- type: object
properties:
type:
const: scheduled-job
id:
type: string
required:
- type
- id
additionalProperties: false
- type: object
properties:
type:
const: duplicated-job
id:
type: string
required:
- type
- id
additionalProperties: false
- type: object
properties:
type:
const: webhook
id:
type: string
required:
- type
- id
additionalProperties: false
status:
type: object
properties:
stage:
enum:
- COMPLETED
- CANCELED
- ERROR
- DELETED
- RUNNING
- SCHEDULING
message:
anyOf:
- type: string
- type: 'null'
cancelReason:
anyOf:
- enum:
- NO_CREDITS
- NO_SUBSCRIPTION
- type: string
failureCount:
type: number
required:
- stage
- message
additionalProperties: false
secrets:
type: array
items:
type: string
labels:
type: object
propertyNames:
type: string
additionalProperties:
type: string
hfToken:
type: object
properties:
ownerName:
type: string
orgName:
type: string
tokenRole:
enum:
- read
- write
- fineGrained
tokenId:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
settingsUrl:
type: string
required:
- ownerName
additionalProperties: false
required:
- id
- createdAt
- environment
- flavor
- createdBy
- type
- owner
- status
additionalProperties: false
description: The list of jobs
parameters:
- name: namespace
in: path
required: true
schema:
type: string
- name: label
in: query
schema:
description: 'Filter jobs by label. Format: ''key=value'' (e.g., ''environment=production'').'
type: string
required: false
post:
summary: Start a job
tags:
- jobs
requestBody:
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
spaceId:
type: string
dockerImage:
type: string
arguments:
type: array
items:
type: string
command:
minItems: 1
type: array
items:
type: string
minLength: 1
environment:
default: {}
type: object
propertyNames:
type: string
pattern: ^[a-zA-Z][_a-zA-Z0-9]+$
additionalProperties:
type: string
secrets:
type: object
propertyNames:
type: string
pattern: ^[a-zA-Z][_a-zA-Z0-9]*$
additionalProperties:
type: string
flavor:
enum:
- 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
arch:
enum:
- amd64
- arm64
timeoutSeconds:
default: null
anyOf:
- type: integer
exclusiveMinimum: 0
maximum: 9007199254740991
- type: 'null'
attempts:
description: 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.
default: 1
type: integer
minimum: 1
maximum: 9007199254740991
labels:
description: 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.
type: object
propertyNames:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9._-]+$
additionalProperties:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9._-]*$
volumes:
description: HuggingFace Buckets or Repos to mount as volumes in the job container.
minItems: 1
type: array
items:
type: object
properties:
type:
enum:
- bucket
- model
- dataset
- space
source:
description: Source identifier, e.g. 'username/my-bucket' or 'username/my-model'
type: string
mountPath:
description: Mount path inside the container, e.g. '/data'
type: string
pattern: ^\/.*
revision:
description: Git revision (only for repos, defaults to 'main')
type: string
readOnly:
description: Read-only mount (true for repos, false default for buckets)
type: boolean
path:
description: Subfolder prefix inside the bucket/repo to mount, e.g. 'path/to/dir'
type: string
required:
- type
- source
- mountPath
required:
- flavor
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
id:
type: string
createdAt:
type: string
format: date-time
pattern: ^((\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-((0[13578]|1[02])-(0[1-9]|[12]\d|3[01])|(0[469]|11)-(0[1-9]|[12]\d|30)|(02)-(0[1-9]|1\d|2[0-8])))T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z)$
spaceId:
type: string
dockerImage:
type: string
timeout:
type: number
environment:
type: object
propertyNames:
type: string
additionalProperties:
type: string
command:
type: array
items:
type: string
arguments:
type: array
items:
type: string
arch:
enum:
- amd64
- arm64
flavor:
enum:
- 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
createdBy:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
additionalProperties: false
retry:
type: number
startedAt:
type: string
format: date-time
pattern: ^((\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-((0[13578]|1[02])-(0[1-9]|[12]\d|3[01])|(0[469]|11)-(0[1-9]|[12]\d|30)|(02)-(0[1-9]|1\d|2[0-8])))T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z)$
finishedAt:
type: string
format: date-time
pattern: ^((\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-((0[13578]|1[02])-(0[1-9]|[12]\d|3[01])|(0[469]|11)-(0[1-9]|[12]\d|30)|(02)-(0[1-9]|1\d|2[0-8])))T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z)$
durations:
type: object
properties:
schedulingSecs:
type: number
runningSecs:
type: number
totalSecs:
type: number
additionalProperties: false
volumes:
type: array
items:
type: object
properties:
type:
type: string
source:
type: string
mountPath:
type: string
revision:
type: string
readOnly:
type: boolean
path:
type: string
required:
- type
- source
- mountPath
additionalProperties: false
type:
const: job
owner:
type: object
properties:
id:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
name:
type: string
type:
enum:
- user
- org
avatarUrl:
type: string
required:
- id
- name
- type
- avatarUrl
additionalProperties: false
initiator:
anyOf:
- type: object
properties:
id:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
name:
type: string
type:
enum:
- user
- org
avatarUrl:
type: string
required:
- id
- name
- type
- avatarUrl
additionalProperties: false
- type: object
properties:
type:
const: scheduled-job
id:
type: string
required:
- type
- id
additionalProperties: false
- type: object
properties:
type:
const: duplicated-job
id:
type: string
required:
- type
- id
additionalProperties: false
- type: object
properties:
type:
const: webhook
id:
type: string
required:
- type
- id
additionalProperties: false
status:
type: object
properties:
stage:
enum:
- COMPLETED
- CANCELED
- ERROR
- DELETED
- RUNNING
- SCHEDULING
message:
anyOf:
- type: string
- type: 'null'
cancelReason:
anyOf:
- enum:
- NO_CREDITS
- NO_SUBSCRIPTION
- type: string
failureCount:
type: number
required:
- stage
- message
additionalProperties: false
secrets:
type: array
items:
type: string
labels:
type: object
propertyNames:
type: string
additionalProperties:
type: string
hfToken:
type: object
properties:
ownerName:
type: string
orgName:
type: string
tokenRole:
enum:
- read
- write
- fineGrained
tokenId:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
settingsUrl:
type: string
required:
- ownerName
additionalProperties: false
required:
- id
- createdAt
- environment
- flavor
- createdBy
- type
- owner
- status
additionalProperties: false
description: The job after it has been started
parameters:
- name: namespace
in: path
required: true
schema:
type: string
/api/jobs/{namespace}/count:
get:
description: Count the number of jobs for an entity with optional status stage filter
summary: Count jobs
tags:
- jobs
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
count:
type: number
required:
- count
additionalProperties: false
description: The count of jobs matching the filter
parameters:
- name: namespace
in: path
required: true
schema:
type: string
- name: stage
in: query
schema:
anyOf:
- enum:
- COMPLETED
- CANCELED
- ERROR
- DELETED
- RUNNING
- SCHEDULING
- type: array
items:
enum:
- COMPLETED
- CANCELED
- ERROR
- DELETED
- RUNNING
- SCHEDULING
required: false
/api/jobs/{namespace}/{jobId}:
get:
summary: Get a job
tags:
- jobs
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
id:
type: string
createdAt:
type: string
format: date-time
pattern: ^((\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-((0[13578]|1[02])-(0[1-9]|[12]\d|3[01])|(0[469]|11)-(0[1-9]|[12]\d|30)|(02)-(0[1-9]|1\d|2[0-8])))T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z)$
spaceId:
type: string
dockerImage:
type: string
timeout:
type: number
environment:
type: object
propertyNames:
type: string
additionalProperties:
type: string
command:
type: array
items:
type: string
arguments:
type: array
items:
type: string
arch:
enum:
- amd64
- arm64
flavor:
enum:
- 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
createdBy:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
additionalProperties: false
retry:
type: number
startedAt:
type: string
format: date-time
pattern: ^((\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468
# --- truncated at 32 KB (137 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hugging-face-transformers/refs/heads/main/openapi/hugging-face-transformers-jobs-api-openapi.yml