Skip to content

Slurm Rest API

Overview

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

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 (1 hour by default).

Login

Refer to the article Connect to MeluXina.

Request a token

Request a token with a default lifespan of 1 hour (3600 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 http://slurmrestd.meluxina.lxp.lu:6820
API_VER The API version string v0.0.38
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-NAME:${USER_NAME}" \
    -H "X-SLURM-USER-TOKEN:${SLURM_JWT}"

Code example:

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


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

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

Example output:

{
  "meta": {
    "plugin": {
      "type": "openapi/v0.0.38",
      "name": "Slurm OpenAPI v0.0.38"
    },
    "Slurm": {
      "version": {
        "major": 22,
        "micro": 5,
        "minor": 5
      },
      "release": "22.05.5"
    }
  },
  "errors": []
}

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

Code example:

curl -X POST ${SLURM_URL}/slurm/${API_VER}/job/submit \
    -H "X-SLURM-USER-NAME:${USER_NAME}" \
    -H "X-SLURM-USER-TOKEN:${SLURM_JWT}" \
    -H "Content-Type: application/json" \
    -d @- <<- EOF
{
    "script": "echo 'Hello, world'",
    "job": {
        "qos": "default",
        "time_limit": 5,
        "account": "${ACCOUNT}",
        "environment": {
            "USER": "u000000"
        }
    }
}
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-NAME': f'{USER_NAME}',
        'X-SLURM-USER-TOKEN': f'{SLURM_JWT}'
    },
    json={
        'script': 'echo "Hello, world"',
        'job': {
            'qos': 'default',
            'time_limit': 5,
            'account': f'{ACCOUNT}',
            'environment': {
                'USER': 'u000000'
            }
        }
    })

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

Output data model: Link

Example output (truncated):

{
  "meta": {
    "plugin": {
      "type": "openapi\/v0.0.38",
      "name": "Slurm OpenAPI v0.0.38"
    },
    "Slurm": {
      "version": {
        "major": 22,
        "micro": 5,
        "minor": 5
      },
      "release": "22.05.5"
    }
  },
  "errors": [],
  "job_id": 123456,
  "step_id": "BATCH",
  "job_submit_user_msg": ""
}

List jobs

Code example:

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

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


response = requests.get(
    f'{SLURM_URL}/slurm/{API_VER}/jobs',
    headers={
        'X-SLURM-USER-NAME': f'{USER_NAME}',
        '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/v0.0.38",
      "name": "Slurm OpenAPI v0.0.38"
    },
    "Slurm": {
      "version": {
        "major": 22,
        "micro": 5,
        "minor": 5
      },
      "release": "22.05.5"
    }
  },
  "errors": [],
  "jobs": [
    {
      "account": "p000000",
      "accrue_time": 1234567890,
      "derived_exit_code": 0,
      "eligible_time": 1234567890,
      "end_time": 1234567890,
      "group_id": 555,
      "group_name": "hpcusers",
      "job_id": 123456,
      "job_resources": {
        "nodes": "mel0000",
        "allocated_cores": 1,
        "allocated_hosts": 1,
        "allocated_nodes": []
      },
      "job_state": "COMPLETED",
      "last_sched_evaluation": 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-NAME:${USER_NAME}" \
    -H "X-SLURM-USER-TOKEN:${SLURM_JWT}"

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


response = requests.get(
    f'{SLURM_URL}/slurm/{API_VER}/job/{JOB_ID}',
    headers={
        'X-SLURM-USER-NAME': f'{USER_NAME}',
        '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/v0.0.38",
      "name": "Slurm OpenAPI v0.0.38"
    },
    "Slurm": {
      "version": {
        "major": 22,
        "micro": 5,
        "minor": 5
      },
      "release": "22.05.5"
    }
  },
  "errors": [],
  "jobs": [
    {
      "account": "p000000",
      "accrue_time": 1234567890,
      "derived_exit_code": 0,
      "eligible_time": 1234567890,
      "end_time": 1234567890,
      "group_id": 555,
      "group_name": "hpcusers",
      "job_id": 123456,
      "job_resources": {
        "nodes": "mel0000",
        "allocated_cores": 1,
        "allocated_hosts": 1,
        "allocated_nodes": []
      },
      "job_state": "COMPLETED",
      "last_sched_evaluation": 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"
    }
  ]
}