NAV Navbar
curl Python

Introduction

Welcome to the Cloudrun API! You can use it to create, configure, and run your own WRF simulations in the cloud, either from command line or from your own custom application. Explore our API docs and feel free to reach out for help at help@cloudrun.co!

We have language bindings in shell (using curl) and Python! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

To authenticate, use this code:

from cloudrun import Run

run = Run('https://api.cloudrun.co/v1', token)
# With curl, pass the authentication header with each request
curl https://api.cloudrun.co/v1/runs \
    -H "Authorization: Bearer $token"

Make sure to set the token parameter to your API token.

Cloudrun uses API tokens to allow access to the API. You can reqest a new Cloudrun API token via e-mail at accounts@cloudrun.co.

Cloudrun expects for the API token to be included in all API requests to the server in a header that looks like this:

Authorization: Bearer $token

Runs

Introduction

A run is the main Cloudrun resource that you will be working with. It allows you to set the parameters of your model run, upload input files, start and stop a run, download output files, or sample model output.

Creating a new run

from cloudrun import Run

run = Run('https://api.cloudrun.co/v1', token)
run.create(model='wrf', version='3.9.1')
curl -X POST https://api.cloudrun.co/v1/runs \
     -H "Authorization: Bearer $token" \
     -F "model=wrf" \
     -F "version=3.9.1"

This endpoint creates a new WRF run, and will return the Run JSON object in the response.

HTTP Request

POST https://api.cloudrun.co/v1/runs

Form parameters

Parameter Description
model Name of model to use, e.g. "wrf"
version Model version to use, e.g. "3.9.1"

Response

The response body contains the Run object.

{
  "compute_config": {},
  "compute_options": [],
  "disk_usage": 0,
  "error": null,
  "id": "cac65d8d-5b91-4fc9-b1b7-8096aa1f3c9e",
  "input_files": [],
  "model": "wrf",
  "output_files": [],
  "percent_complete": 0.0,
  "remaining_time": null,
  "required_input_files": [
    "namelist.input"
  ],
  "run_name": null,
  "selected_compute_option": {},
  "status": "created",
  "time_created": "2018-08-21T02:16:59.707338Z",
  "time_started": null,
  "time_stopped": null,
  "version": "3.9.1"
}

Most runs endpoints return a Run object in JSON format in the response body. See an example response on the right.

Getting all runs

Get a specific run

from cloudrun import Run

run = Run('https://api.cloudrun.co/v1', token, id=id)
curl https://api.cloudrun.co/v1/runs/$id \
    -H "Authorization: Bearer $token"

This endpoint retrieves a specific WRF run that you own or have access to.

URL parameters

Parameter Description
id The id of the WRF run to retrieve

Response

The response body contains the Run object.

Uploading input files

run.upload(file=path_to_file)
curl -X POST https://api.cloudrun.co/v1/runs/${id}/input \
     -H "Authorization: Bearer $token" \
     -F "file=@$path_to_file"

path_to_file parameter must point to a valid input file, e.g. wrfinput_d01.

The response body will look like this, for example when uploading the WRF namelist file namelist.input:

{
  "file": {
    "id": "a3d32942-b172-435d-9354-d49f4b1cfef8",
    "name": "namelist.input",
    "size": 4438
  }
}

where id is the id assigned to the uploaded input file.

This endpoint lets you upload an input file to your run.

HTTP Request

POST https://api.cloudrun.co/v1/runs/{id}/input

Form parameters

Parameter Description
file Path to a valid input file

Response

Parameter Description
id Unique ID of your input file
name File name
size File size in bytes

Uploading input files from URL

run.upload(url=url_to_file)
curl -X POST https://api.cloudrun.co/v1/runs/${id}/input \
     -H "Authorization: Bearer $token" \
     -F "url=$url_to_file"

url_to_file parameter must point to a valid input file on the web, e.g. wrfinput_d01. This could be a file hosted from an http or ftp server, or an AWS S3 bucket.

The response body will look like this, for example when uploading the WRF namelist file namelist.input from url:

{
  "file": {
    "id": "a3d32942-b172-435d-9354-d49f4b1cfef8",
    "name": "namelist.input",
    "size": 4438
  }
}

This endpoint lets you upload an input file from a remote URL to your run.

HTTP Request

POST https://api.cloudrun.co/v1/runs/{id}/input

Form parameters

Parameter Description
url URL to a remote input file

Response

Parameter Description
id Unique ID of your input file
name File name
size File size in bytes

Selecting your compute option

curl -X PATCH ${CLOUDRUN_API_URL}/runs/${id} \
     -H "Authorization: Bearer $CLOUDRUN_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '[{"op":"replace","path":"/selected_compute_option","value":{"compute_option_id":"'${compute_option_id}'"}}]'

After you have uploaded a valid WRF namelist file (namelist.input), Cloudrun server will parse the namelist and return a number of available compute options in the response. Each option uses a different number of parallel cores, and has different estimated time to completion and run price.

"compute_options": [
  {
    "compute_option_id": "ee418969-e1de-4f44-b053-d8349baf01aa",
    "cores": 2,
    "cost": "1.0",
    "time": 23
  },
  {
    "compute_option_id": "d3762d0d-5a83-4b56-bd48-7b6f2467efea",
    "cores": 4,
    "cost": "1.14",
    "time": 16
  },
  {
    "compute_option_id": "bb20dc53-50ee-4178-ad4a-c14518b8420d",
    "cores": 8,
    "cost": "1.9",
    "time": 12
  },
  {
    "compute_option_id": "06f75013-84db-42c3-80b4-e4fa733df6ea",
    "cores": 16,
    "cost": "3.16",
    "time": 10
  },
  {
    "compute_option_id": "7a3ecb91-a0c7-4f51-85c1-b62e7a7bf69d",
    "cores": 32,
    "cost": "5.21",
    "time": 10
  }
]

HTTP Request

PATCH https://api.cloudrun.co/v1/runs/{id}

The request must include a JSON patch in the body, for example:

[
  {
    "op": "replace",
    "path": "/selected_compute_option",
    "value": {"compute_option_id": "7a3ecb91-a0c7-4f51-85c1-b62e7a7bf69d"}
  }
]

Form parameters

Parameter Description
compute_option_id A unique ID that matches one of IDs in compute_options member of the Run JSON object

Response

The response body contains the Run JSON object.

Starting your WRF run

run.start(cores=32)

# or

run.start(compute_option_id=compute_id)
curl -X POST https://api.cloudrun.co/v1/runs/${id}/start \
     -H "Authorization: Bearer $token"

Use this endpoint to start your run once it has been properly configured and all the input files have been uploaded.

If using the HTTP API (e.g. via curl), you must set the value of selected_compute_option firsti using the PATCH request to https://api.cloudrun.co/v1/runs/${id}.

If using the Python interface to the API, you can provide the number of cores or compute_option_id as an argument to run.start().

HTTP Request

POST https://api.cloudrun.co/v1/runs/{id}/start

Form parameters

One or the other of the two parameters (cores or compute_option_id) can be used in the Python interface only.

Parameter Description
cores Number of compute cores to use
compute_option_id Unique ID of one of available compute options

Response

The response body contains the Run JSON object.

Stopping your WRF run

run.stop()
curl -X POST https://api.cloudrun.co/v1/runs/${id}/stop \
     -H "Authorization: Bearer $token"

Use this endpoint to stop a currently active run. This should be necessary only if you want to stop your run before it completes.

HTTP Request

POST https://api.cloudrun.co/v1/runs/{id}/stop

Response

The response body contains the Run JSON object.

Deleting your WRF run

run.delete()
curl -X DELETE https://api.cloudrun.co/v1/runs/${id} \
     -H "Authorization: Bearer $token"

Use this endpoint to delete the output files from your run. You will still be able to access the metadata of your run.

HTTP Request

DELETE https://api.cloudrun.co/v1/runs/{id}

Response

The response body contains the Run JSON object.

Errors

The Cloudrun API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is incorrect.
401 Unauthorized -- Your API token is wrong.
403 Forbidden -- The resource requested is hidden for administrators only.
404 Not Found -- The specified resource could not be found.
429 Too Many Requests -- Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.