Skip to content

Slurm Rest API

Overview

The Slurm Rest API allows users to interact with Slurm from a standard HTTP REST API.

Use the right URL

From the MeluXina cloud partition, use https://slurm.cloud.lxp.lu/

Otherwise, use https://slurm-api.lxp.lu by default (from your local environment, the MeluXina login nodes, the MeluXina compute nodes, ...)

Gaining access

Single time operation

You do not have to request a token every time you want to interact with the Slurm Rest API.

You can store and reuse the token during its lifespan (30 minutes by default).

Login

Refer to the article Connect to MeluXina.

Request a token

Request a token with a default lifespan of 30 minutes (1800 seconds):

scontrol token

Request a token with a user-defined lifespan:

scontrol token lifespan=${seconds}

A new token will be generated and displayed:

SLURM_JWT=hyKGTt689.2Ybk59ncedhh84s

Token privacy

The tokens obtained by running scontrol token identifies users and should not be shared.

We advise users to store their tokens in a safe location, e.g. a password manager.

Operations

This documentation uses the following variables:

Variable Description Example value
SLURM_JWT The token returned by scontrol token, without SLURM_JWT= hyKGTt689.2Ybk59ncedhh84s
USER_NAME Your username on MeluXina u000000
SLURM_URL The Slurm Rest API URL https://slurm-api.lxp.lu
API_VER The API version string v0.0.43
ACCOUNT You project name on MeluXina p000000

Ping (test) the API

Code example:

curl -X GET ${SLURM_URL}/slurm/${API_VER}/ping \
    -H "X-SLURM-USER-TOKEN:${SLURM_JWT}"

Code example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import requests
import json


response = requests.get(
    f'{SLURM_URL}/slurm/{API_VER}/ping',
    headers={
        'X-SLURM-USER-TOKEN': f'{SLURM_JWT}'
    })

response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Example output (truncated):

{
  "pings": [
    {
      "hostname": "slurm01",
      "pinged": "UP",
      "responding": true,
      "latency": 2565,
      "mode": "primary",
      "primary": true
    },
  ],
  "meta": {
    "plugin": {
      "type": "openapi/slurmctld",
      "name": "Slurm OpenAPI slurmctld",
      "data_parser": "data_parser/v0.0.43",
      "accounting_storage": "accounting_storage/slurmdbd"
    },
    "slurm": {
      "version": {
        "major": "25",
        "micro": "5",
        "minor": "05"
      },
      "release": "25.05.5",
      "cluster": "meluxina"
    }
  },
  "errors": [],
  "warnings": []
}

Run a job

Job properties

The following job properties are mandatory on MeluXina, even if marked as optional in the Slurm API documentation:

  • qos
  • time_limit
  • account
  • environment
  • current_working_directory

Code example:

curl -X POST ${SLURM_URL}/slurm/${API_VER}/job/submit \
    -H "X-SLURM-USER-TOKEN:${SLURM_JWT}" \
    -H "Content-Type: application/json" \
    -d @- <<- EOF
{
    "script": "echo 'Hello, world'",
    "job": {
        "qos": "default",
        "time_limit": 5,
        "current_working_directory": "/home/users/${USER_NAME}",
        "account": "${ACCOUNT}",
        "environment": [
            "ENV_VAR=example_value"
        ]
    }
}
EOF

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import requests
import json


response = requests.post(
    f'{SLURM_URL}/slurm/{API_VER}/job/submit',
    headers={
        'X-SLURM-USER-TOKEN': f'{SLURM_JWT}'
    },
    json={
        'script': 'echo "Hello, world"',
        'job': {
            'qos': 'default',
            'time_limit': 5,
            'account': f'{ACCOUNT}',
            "current_working_directory": f'/home/users/{USER_NAME}',
            'environment': [
                'ENV_VAR=example_value'
            ]
        }
    })

response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Output data model: Link

Example output (truncated):

{
  "job_id": 4396069,
  "step_id": "batch",
  "job_submit_user_msg": "",
  "meta": {
    "plugin": {
      "type": "openapi\/slurmctld",
      "name": "Slurm OpenAPI slurmctld",
      "data_parser": "data_parser\/v0.0.43",
      "accounting_storage": "accounting_storage\/slurmdbd"
    },
    "command": [
    ],
    "slurm": {
      "version": {
        "major": "25",
        "micro": "5",
        "minor": "05"
      },
      "release": "25.05.5",
      "cluster": "meluxina"
    }
  },
  "errors": [],
  "warnings": []
}

List jobs

Code example:

curl -X GET ${SLURM_URL}/slurm/${API_VER}/jobs \
    -H "X-SLURM-USER-TOKEN:${SLURM_JWT}"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import requests
import json


response = requests.get(
    f'{SLURM_URL}/slurm/{API_VER}/jobs',
    headers={
        'X-SLURM-USER-TOKEN': f'{SLURM_JWT}'
    })

response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Output data model: Link

Example output (truncated):

{
  "meta": {
    "plugin": {
      "type": "openapi/slurmctld",
      "name": "Slurm OpenAPI slurmctld",
      "data_parser": "data_parser/v0.0.43",
      "accounting_storage": "accounting_storage/slurmdbd"
    },
    "slurm": {
      "version": {
        "major": "25",
        "micro": "5",
        "minor": "05"
      },
      "release": "25.05.5",
      "cluster": "meluxina"
    }
  },
  "errors": [],
  "warnings": [],
  "jobs": [
    {
      "account": "p000000",
      "accrue_time": {
        "set": true,
        "infinite": false,
        "number": 1234567890
      },
      "eligible_time": {
        "set": true,
        "infinite": false,
        "number": 1234567890
      },
      "end_time": {
        "set": true,
        "infinite": false,
        "number": 1234567890
      },
      "group_id": 555,
      "group_name": "hpcusers",
      "job_id": 123456,
      "job_state": [
        "RUNNING",
        "CONFIGURING"
      ],
      "last_sched_evaluation": {
        "set": true,
        "infinite": false,
        "number": 1234567890
      },
      "tres_req_str": "cpu=1,mem=480G,node=1,billing=1",
      "tres_alloc_str": "cpu=256,mem=480G,node=1,billing=256,gres/cpun=1",
      "user_id": 15000,
      "user_name": "u000000"
    }
  ]
}

Get a job status

Code example:

curl -X GET ${SLURM_URL}/slurm/${API_VER}/job/${JOB_ID} \
    -H "X-SLURM-USER-TOKEN:${SLURM_JWT}"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import requests
import json


response = requests.get(
    f'{SLURM_URL}/slurm/{API_VER}/job/{JOB_ID}',
    headers={
        'X-SLURM-USER-TOKEN': f'{SLURM_JWT}'
    })

response.raise_for_status()
print(json.dumps(response.json(), indent=2))

Output data model: Link

Example output (truncated):

{
  "meta": {
    "plugin": {
      "type": "openapi/slurmctld",
      "name": "Slurm OpenAPI slurmctld",
      "data_parser": "data_parser/v0.0.43",
      "accounting_storage": "accounting_storage/slurmdbd"
    },
    "slurm": {
      "version": {
        "major": "25",
        "micro": "5",
        "minor": "05"
      },
      "release": "25.05.5",
      "cluster": "meluxina"
    }
  },
  "errors": [],
  "warnings": [],
  "jobs": [
    {
      "account": "p000000",
      "accrue_time": {
        "set": true,
        "infinite": false,
        "number": 1234567890
      },
      "eligible_time": {
        "set": true,
        "infinite": false,
        "number": 1234567890
      },
      "end_time": {
        "set": true,
        "infinite": false,
        "number": 1234567890
      },
      "group_id": 555,
      "group_name": "hpcusers",
      "job_id": 123456,
      "job_state": [
        "RUNNING",
        "CONFIGURING"
      ],
      "last_sched_evaluation": {
        "set": true,
        "infinite": false,
        "number": 1234567890
      },
      "tres_req_str": "cpu=1,mem=480G,node=1,billing=1",
      "tres_alloc_str": "cpu=256,mem=480G,node=1,billing=256,gres/cpun=1",
      "user_id": 15000,
      "user_name": "u000000"
    }
  ]
}