Using Rescale’s REST API

With Rescale’s REST API you can upload input files, create jobs, view the status of existing jobs, and more. For the full list of API endpoints, see the Rescale API Documentation.

An API key is required to authenticate your account when interacting with the API. To generate an API key for your account, go to the API section of your settings page (Profile > User Profile Settings > API), then click the Add API Key button.

There’s no limit to how many API keys you can create, and deleting them is as easy as selecting and clicking “delete.” API keys are set to never expire by default, but if you need to set a max lifetime policy, reach out to Rescale Support for assistance. A max lifetime policy will include an API key lifetime in days (e.g. 90 days). Once a max lifetime policy is set, all new API keys created after the policy creation date will include an expiration date.

For example: if your max lifetime policy is set to 90 days on 1/1/23, any API keys created after that time will expire 90 days after the creation of the API key. If I create an API key on 2/13/23, then the API key will expire on 5/14/23

By default, the API key is hidden. In order to reveal it, simply click on the API key. You can copy the API key by clicking the copy icon to the right.

API Key FAQs

Q. Can I set the API max lifetime policy on a user-level?
A. No, API max lifetime policies are set on the Organization-level only

Q. What happens when an API key expires?
A. When an API key expires, the date will turn red, but the API key will continue to exist. When attempting to use the API key, an error will be thrown that says “API key is no longer active”. It is up to the user to delete API keys when they expire.

Q. Are there any alerts tied to the expiration date?
A. No, there are no alerts tied to the expiration date today. If you are interested in this, please reach out to Rescale to voice your need.

Q. Is it possible to add permissions on the key-level?
A. No, all keys will have full permissions to whatever the user has access to.

Q. What happens to the API key if a user is deactivated?
A. If you deactivate a user and try to use one of the keys you get the message: User inactive or deleted.

Running a Job through the Rescale API

This example shows how to set up a LS-DYNA job through the API using both cURL and python.

First, navigate to the directory containing the input file (input.zip) and upload using the command:

curl -X POST -H 'Content-Type:multipart/form-data' \-H 'Authorization: Token <api-token>' \-F "file=@input.zip" \https://platform.rescale.com/api/v2/files/contents/

The response would be similar to:

{
  "pathParts": {
    "path": "user/user_WrNSdb/input-a2f3d113-6591-461e-a912-57b06166df21.zip",
    "container": "prod-rescale-platform"
  },
  "typeId": 1,
  "name": "input.zip",
  "dateUploaded": "2016-11-11T18:50:54.078468Z",
  "relativePath": "input.zip",
  "storage": {
    "storageType": "S3Storage",
    "id": "pCTMk",
    "connectionSettings": {
      "region": "us-east-1"
    },
    "encryptionType": "default"
  },
  "decryptedSize": 10391660,
  "downloadUrl": "https://platform.rescale.com/api/v2/files/yMqdxd/contents/",
  "sharedWith": [],
  "encodedEncryptionKey": "N1iq48GWyEDkMG1wTHI656hcJZKdSQecuwKhu31Epd0=",
  "owner": "demo@example.com",
  "path": "user/user_WrNSdb/input-a2f3d113-6591-461e-a912-57b06166df21.zip",
  "isUploaded": true,
  "viewInBrowser": false,
  "id": "yMqdxd",
  "isDeleted": false,
  "md5": "159bb1cdd01987f9122f5ec673958eaf"
}

Next, we have to choose an analysis software. The complete list of analyses can be obtained by calling curl -H "Authorization: Token <api-token>" https://platform.rescale.com/api/v2/analyses/. The important information to extract is the code of the Software that you would like to use, shown under "code":"...".

You will also need the coretype information, which can by found using curl -H "Authorization: Token <api-token>" https://platform.rescale.com/api/v2/coretypes/. The name of the coretypes as displayed on the Web UI is captured under "name":"..." in each entry. Similarly, you need to extract the code of the coretype, shown under "code":"...".

In the same directory that you are currently on, create a data file containing a JSON of the job settings and info. The ID of the input file can be found in the response when the input file was uploaded. For example:

cat <<EOF > data.json{  "name": "LS-DYNA cURL API Setup", "billingPriorityValue": "INSTANT", "jobanalyses": [    {      "useRescaleLicense":true,      "command": "ls-dyna -n 2 -i neon.refined.rev01.k -p single",      "analysis": {        "code": "ls_dyna",        "version": "9.0.0"      },      "hardware": {        "coresPerSlot": 2,        "slots": 1,        "coreType": "hpc-3"      },      "inputFiles": [        {          "id": "yMqdxd"        }      ]    }  ]}EOF

The full list of command options and its defaults can be found here.

Next, run the command to set up your Rescale job based on the data file that was just created:

curl -X POST --data @data.json \-H "Authorization: Token <api-token>" \-H "Content-Type: application/json" \https://platform.rescale.com/api/v2/jobs/

The response would be similar to:

{   "monteCarloIterations":null,   "paramFile":null,   "name":"LS-DYNA cURL API Setup",  "billingPriorityValue": "INSTANT", "includeNominalRun":false,   "jobanalyses":[      {         "envVars":{          },         "preProcessScriptCommand":"",         "postProcessScriptCommand":"",         "postProcessScript":null,         "useRescaleLicense":true,         "templateTasks":[          ],         "analysis":{            "version":"9.0.0",            "code":"ls_dyna",            "name":"LS-DYNA",            "versionName":"R9.0.0"         },         "hardware":{            "coresPerSlot":2,            "coreType":"hpc-3",            "coreSummary":{               "storagePerNode":80000,               "gpusPerNode":0,               "numberOfNodes":1.0,               "memoryPerNode":7500            },            "slots":1,            "type":"compute",            "walltime":750         },         "command":"ls-dyna -n 2 -i neon.refined.rev01.k -p single",         "preProcessScript":null,         "flags":{          },         "inputFiles":[            {               "pathParts":{                  "path":"user/user_WrNSdb/input-a2f3d113-6591-461e-a912-57b06166df21.zip",                  "container":"prod-rescale-platform"               },               "typeId":1,               "name":"input.zip",               "dateUploaded":"2016-11-11T18:50:54.078468Z",               "relativePath":"input.zip",               "storage":{                  "storageType":"S3Storage",                  "id":"pCTMk",                  "connectionSettings":{                     "region":"us-east-1"                  },                  "encryptionType":"default"               },               "decryptedSize":10391660,               "downloadUrl":"https://platform.rescale.com/api/v2/files/yMqdxd/contents/",               "sharedWith":[                ],               "encodedEncryptionKey":"N1iq48GWyEDkMG1wTHI656hcJZKdSQecuwKhu31Epd0=",               "owner":"demo@rescale.com",               "path":"user/user_WrNSdb/input-a2f3d113-6591-461e-a912-57b06166df21.zip",               "isUploaded":true,               "viewInBrowser":false,               "id":"yMqdxd",               "isDeleted":false,               "md5":"159bb1cdd01987f9122f5ec673958eaf"            }         ]      }   ],   "projectId":null,   "resourceFilters":[    ],   "remoteVizConfig":null,   "jobvariables":[    ],   "sshPort":22,   "expectedRuns":null,   "caseFile":null,   "isLowPriority":false,   "owner":"demo@rescale.com",   "isTemplateDryRun":false,   "autoTerminateCluster":true,   "id":"RcAFeb",   "archiveFilters":[]}

The job is now saved and will appear in the Rescale Web UI. Finally, you need to submit the job using the command:

curl -X POST -H 'Authorization: Token <api-token>' \https://platform.rescale.com/api/v2/jobs/RcAFeb/submit/

Note: The Job ID can be found in the previous response.

If you want to monitor the status of your job, use the command:

curl -H 'Authorization: Token <api-token>' \https://platform.rescale.com/api/v2/jobs/RcAFeb/statuses/

The response would be similar to:

{   "count":6,   "previous":null,   "results":[      {         "status":"Completed",         "statusDate":"2016-11-15T19:01:13.948641Z",         "id":"KNwnm",         "statusReason":"Completed successfully"      },      {         "status":"Executing",         "statusDate":"2016-11-15T18:47:05.530000Z",         "id":"ePisa",         "statusReason":null      },      {         "status":"Validated",         "statusDate":"2016-11-15T18:41:23.929000Z",         "id":"Yfcem",         "statusReason":null      },      {         "status":"Started",         "statusDate":"2016-11-15T18:41:23.629000Z",         "id":"KDisa",         "statusReason":null      },      {         "status":"Queued",         "statusDate":"2016-11-15T18:41:21.577545Z",         "id":"ircem",         "statusReason":null      },      {         "status":"Pending",         "statusDate":"2016-11-15T18:40:56.465755Z",         "id":"UOisa",         "statusReason":null      }   ],   "next":null}

A job also can be set up through a python script. This example provides chunks of sample python code that can be used to set up and run a LS-DYNA job.

Note: This method uses the requests library, so you have to run import requests at the start of your code.

First, zip the file and then upload to Rescale using:

file_upload = requests.post(  'https://platform.rescale.com/api/v2/files/contents/',  data=None,  files={'file': open('input.zip','rb')},  headers={'Authorization': 'Token <api-token>'} )print file_upload.content

Note that the file (input.zip) must be in the same directory as the script.

The output would be similar to:

{   "pathParts":{      "path":"user/user_WrNSdb/input-69b6c9bd-e4d8-4291-9c79-487ac21a0c7c.zip",      "container":"prod-rescale-platform"   },   "typeId":1,   "name":"input.zip",   "dateUploaded":"2016-11-14T22:58:35.729270Z",   "relativePath":"input.zip",   "storage":{      "storageType":"S3Storage",      "id":"pCTMk",      "connectionSettings":{         "region":"us-east-1"      },      "encryptionType":"default"   },   "decryptedSize":10391660,   "downloadUrl":"https://platform.rescale.com/api/v2/files/FDXpJd/contents/",   "sharedWith":[    ],   "encodedEncryptionKey":"ixay5gbPcYHnSwKNhPHldhzCZXEpN/rpD9Q8tskoavo=",   "owner":"demo@rescale.com",   "path":"user/user_WrNSdb/input-69b6c9bd-e4d8-4291-9c79-487ac21a0c7c.zip",   "isUploaded":true,   "viewInBrowser":false,   "id":"FDXpJd",   "isDeleted":false,   "md5":"159bb1cdd01987f9122f5ec673958eaf"}

Next, you will need to set up the job. For this, you will need to obtain the Analyses Software and Hardware information.

For Analyses:

requests.get(  'https://platform.rescale.com/api/v2/analyses/',  headers={'Authorization': 'Token <api-token>'} )

For Coretype:

requests.get(  'https://platform.rescale.com/api/v2/coretypes/',  headers={'Authorization': 'Token <api-token>'} )

In both cases, you need to retrieve the code displayed under "code":"...".

An example of setting up a job would be:

job_setup = requests.post(    'https://platform.rescale.com/api/v2/jobs/',    json = {         "name": "LS-DYNA Python API Setup",         "jobanalyses": [             {                 "useRescaleLicense":True,                 "command": "ls-dyna -n 2 -i neon.refined.rev01.k -p single",                 "analysis": {                     "code": "ls_dyna",                     "version": "9.0.0"                    },                 "hardware": {                     "coresPerSlot": 2,                     "slots": 1,                     "coreType": "hpc-3"                    },                 "inputFiles": [                     {                         "id": "FDXpJd"                        }                    ]                }            ]        },  headers={'Authorization': 'Token <api-token>'} )print job_setup.content

Note: You can find the input file ID from the previous output (file upload)

The output would be similar to:

{   "monteCarloIterations":null,   "paramFile":null,   "name":"LS-DYNA Python API Setup",   "includeNominalRun":false,   "jobanalyses":[      {         "envVars":{          },         "preProcessScriptCommand":"",         "postProcessScriptCommand":"",         "postProcessScript":null,         "useRescaleLicense":true,         "templateTasks":[          ],         "analysis":{            "version":"9.0.0",            "code":"ls_dyna",            "name":"LS-DYNA",            "versionName":"R9.0.0"         },         "hardware":{            "coresPerSlot":2,            "coreType":"hpc-3",            "coreSummary":{               "storagePerNode":80000,               "gpusPerNode":0,               "numberOfNodes":1.0,               "memoryPerNode":7500            },            "slots":1,            "type":"compute",            "walltime":750         },         "command":"ls-dyna -n 2 -i neon.refined.rev01.k -p single",         "preProcessScript":null,         "flags":{          },         "inputFiles":[            {               "pathParts":{                  "path":"user/user_WrNSdb/input-69b6c9bd-e4d8-4291-9c79-487ac21a0c7c.zip",                  "container":"prod-rescale-platform"               },               "typeId":1,               "name":"input.zip",               "dateUploaded":"2016-11-14T22:58:35.729270Z",               "relativePath":"input.zip",               "storage":{                  "storageType":"S3Storage",                  "id":"pCTMk",                  "connectionSettings":{                     "region":"us-east-1"                  },                  "encryptionType":"default"               },               "decryptedSize":10391660,               "downloadUrl":"https://platform.rescale.com/api/v2/files/FDXpJd/contents/",               "sharedWith":[                ],               "encodedEncryptionKey":"ixay5gbPcYHnSwKNhPHldhzCZXEpN/rpD9Q8tskoavo=",               "owner":"demo@rescale.com",               "path":"user/user_WrNSdb/input-69b6c9bd-e4d8-4291-9c79-487ac21a0c7c.zip",               "isUploaded":true,               "viewInBrowser":false,               "id":"FDXpJd",               "isDeleted":false,               "md5":"159bb1cdd01987f9122f5ec673958eaf"            }         ]      }   ],   "projectId":null,   "resourceFilters":[    ],   "remoteVizConfig":null,   "jobvariables":[    ],   "sshPort":22,   "expectedRuns":null,   "caseFile":null,   "isLowPriority":false,   "owner":"demo@rescale.com",   "isTemplateDryRun":false,   "autoTerminateCluster":true,   "id":"ASwPT",   "archiveFilters":[    ]}

The job is now saved and will appear in the Rescale Web UI. Finally, you need to submit the job using the command:

requests.post(  'https://platform.rescale.com/api/v2/jobs/ASwPT/submit/',  headers={'Authorization': 'Token <api-token>'} )

If you would like to monitor your job, you can run the command:

job_status = requests.get(  'https://platform.rescale.com/api/v2/jobs/ASwPT/statuses/',  headers={'Authorization': 'Token <api-token>'} )print job_status.content