AnyLogic
Expand
Search
Font size

Cloud REST API

Applies to AnyLogic Cloud 2.5.0. Last modified on November 20, 2024.

The AnyLogic Cloud API is versioned. The root address contains the version number: for example, the root address for version 8.5.0 for AnyLogic Cloud subscribers is https://cloud.anylogic.com/api/open/8.5.0.

In Private Cloud, the address would look like this: <your Private Cloud instance address>/api/open/8.5.0.

To send a request to the Cloud REST API, you must provide the authorization header in the following format: Authorization: <API key>. To obtain an API key, go to your user profile in the Cloud web UI.
To access specific models and versions, you need must have either developer or user permissions for them.
Some requests require objects in the request body. These are described in the Data model section.

Endpoints

Endpoint Description
GET /models Returns the array of all models belonging to the user (the owner of the API key).
GET /models/<model id> Returns the model with the specified ID.
GET /models/<model ID>/versions/number/<version number> Returns the model version with the specified number (version numbering starts at 1).

Requires exactly one model to be found after filtering, otherwise returns an error.
GET /models/<model ID>/versions/<version ID> Returns the model version with the specified ID.
POST /models/name/ Returns the model with the given name. The request body should contain the model’s name in string form.
GET /versions/<version ID>/experiments Retrieves the array of experiments created for the given model version.
POST /versions/<version ID>/runs Requests the execution of a simulation run with the inputs contained in the run request. This will only result in a real new simulation if such a run has not already been performed. Returns the experiment run, but does not wait for the simulation to complete, so does not return the outputs.
The run request is required in the request body.
POST /versions/<version ID>/runs/stop Stops execution of the model run specified in the request body. Does not return anything.
The run request is required in the request body.
POST /versions/<version ID>/run Returns the experiment run, including the status of the run.
The run request is required in the request body.
POST /versions/<version ID>/results/<run ID> Returns the outputs of the completed run with the specified ID according to the provided output template (so that you can control which data you will receive). If the run did not complete, it returns 404.
Empty outputs are required in the request body.
POST /versions/<version ID>/results Returns the Outputs (experiment results) associated with the model version specified by its ID, according to the outputs template provided in the request body.
Does not require the run ID.
If the results are not found, throws an exception. The experiment result request is required in the request body.
POST /versions/<version ID>/runs/animation Launches an animated model run. Waits for the animation to start, and returns the Animation SVG Run Info object which contains the host address of the node where the animated run was created.
If the request is successful and the animation run starts, a timer is also started for the successful rendering of the animation. If the animation does not render, the run ends after a timeout (in 5 minutes). This is done to prevent runs with AnyLogic Cloud animations from getting stuck indefinitely. It is possible to end such runs in the administrator panel, or by restarting executor.
The run request is required in the request body.
GET /output-file Generates and returns the pre-signed download URL for an output file. The resulting URL can be used to download the file from the AnyLogic Cloud file storage for a limited amount of time (5 minutes).
Requires the file hash and file name to be passed as the hash and filename string parameters, respectively.
POST /upload-file Uploads the file to the Cloud instance and returns the file’s hash.
Requires the file to be present in the request body, in the byte array format.
GET /check-file Checks if the file with the specified hash exists in the Cloud instance. Returns true or false.
Requires the file hash to be passed as the hash parameter of the type String.

There are other endpoints for communicating with the animated run (changing speed, pausing, and so on). These make sense in the browser environment: consider checking out the JavaScript API.

Data model

The AnyLogic Cloud data structure is shown on the diagram below.

To access the models listed on the My Models screen, use the API key displayed in your user’s profile.

Each model may have multiple versions. Experiments are run in the context of the version, not the model. AnyLogic Cloud keeps the inputs and outputs of all the experiments that have been ever run on each model version.

AnyLogic Cloud: Data model

Model

Model is a simple object with a unique ID, a name, a description, an array of version IDs, and a flag indicating whether it is public (true) or private. 
{
    "id": "f7771cd8-8d55-486a-b255-10459a349093",
    "name": "Flocks of Boids",
    "description": "Original Boids, developed by Craig Reynolds, is an artificial life program ",
    "modelVersions": [
        "7c702819-b413-417b-aa61-60becd029e3c",
        "de699d41-1f0c-497d-b544-413685f82d2b",
        "b845d4f9-972c-45c7-ae6a-7a762ab81c03"
    ],
    "published": false
}

Version

The Version object contains complete information about the model’s inputs, outputs, and dashboard configuration in its experimentTemplate field.
The inputs array of this object contains the model’s system inputs: {STOP_TIME}, {MAX_MEMORY_MB}, and so on, as well as the user-defined inputs.
The value field contains the default value of the input and is always a string regardless of the input type.
The outputs array is not the actual outputs of some simulation run (those are described by the Outputs object), but a list of outputs that are available for this particular model version. Therefore, the values of these fields are always null.
The dashboard configuration is irrelevant from the point of view of the API user, so it is omitted from the example. 
{
    "id": "def089c4-96a3-40f2-aefb-de1af471fe2f",
    "version": 6,
    "experimentTemplate": {
        "inputs": [
            {
                "name": "{STOP_MODE}",
                "type": "STRING",
                "units": null,
                "value": "STOP_MODE_AT_TIME"
            },
            {
                "name": "{START_TIME}",
                "type": "DOUBLE",
                "units": "SECOND",
                "value": "0"
            },
            {
                "name": "{STOP_TIME}",
                "type": "DOUBLE",
                "units": "SECOND",
                "value": "1000000"
            },
            {
                "name": "{START_DATE}",
                "type": "DATE_TIME",
                "units": null,
                "value": "2019-05-15T00:00"
            },
            {
                "name": "{STOP_DATE}",
                "type": "DATE_TIME",
                "units": null,
                "value": "2019-05-26T13:46:40"
            },
            {
                "name": "{MAX_MEMORY_MB}",
                "type": "INTEGER",
                "units": null,
                "value": "512"
            },
            {
                "name": "Arrival rate",
                "type": "DOUBLE",
                "units": null,
                "value": "1"
            },
            {
                "name": "Mean service time",
                "type": "DOUBLE",
                "units": null,
                "value": "2"
            },
            {
                "name": "Server capacity",
                "type": "INTEGER",
                "units": null,
                "value": "3"
            },
            {
                "name": "Check failure probability",
                "type": "DOUBLE",
                "units": null,
                "value": "0.2"
            }
        ],
        "outputs": [
            {
                "name": "Queue size stats",
                "type": "STATISTICS_CONTINUOUS",
                "units": null,
                "value": null
            },
            {
                "name": "Total time in system|Total time in system",
                "type": "HISTOGRAM_DATA",
                "units": null,
                "value": null
            },
            {
                "name": "Utilization|Server utilization",
                "type": "DOUBLE",
                "units": null,
                "value": null
            },
            {
                "name": "Mean queue size|Mean queue size",
                "type": "DOUBLE",
                "units": null,
                "value": null
            }
        ],
        "dashboard": { }
    }
}

Experiment

The Experiment object contains the input settings of an experiment stored in AnyLogic Cloud.
Use it to set the inputs of a run by calling the createInputsFromExperiment() function of the CloudClient object.
The value field of an input item always contains a string. For example, for an input of the range type ("FIXED_RANGE_INTEGER"), it is an unparsed JSON string that contains the min, max, and step fields.
Possible values for the type field are listed below. The unit field can be null or one of the values listed in the Units section. 
{
    "uuid": "f3f441f3-8117-4423-9b1c-75b4680c715b",
    "modelVersion": "def089c4-96a3-40f2-aefb-de1af471fe2f",
    "name": "Server Capacity Variation",
    "type": "PARAMETER_VARIATION",
    "inputs": [
        {
            "name": "Arrival rate",
            "type": "DOUBLE",
            "units": null,
            "value": "1"
        },
        {
            "name": "Check failure probability",
            "type": "DOUBLE",
            "units": null,
            "value": "0.2"
        },
        {
            "name": "Mean service time",
            "type": "DOUBLE",
            "units": null,
            "value": "2"
        },
        {
            "name": "Server capacity",
            "type": "FIXED_RANGE_INTEGER",
            "units": null,
            "value": "{\"min\":3,\"max\":7,\"step\":1}"
        },
        {
            "name": "{MAX_MEMORY_MB}",
            "type": "INTEGER",
            "units": null,
            "value": "512"
        },
        {
            "name": "{RANDOM_SEED}",
            "type": "LONG",
            "units": null,
            "value": "1"
        },
        {
            "name": "{START_DATE}",
            "type": "DATE_TIME",
            "units": null,
            "value": "2019-05-15T00:00"}
        ,
        {
            "name": "{START_TIME}",
            "type": "DOUBLE",
            "units": "SECOND",
            "value": "0"
        },
        {
            "name": "{STOP_DATE}",
            "type": "DATE_TIME",
            "units": null,
            "value": "2019-05-26T13:46:40"
        },
        {
            "name": "{STOP_MODE}",
            "type": "STRING",
            "units": null,
            "value": "STOP_MODE_AT_TIME"
        },
        {
            "name": "{STOP_TIME}",
            "type": "DOUBLE",
            "units": "SECOND",
            "value": "1000000"
        }
    ]
}

Outputs

The Outputs object is complex. Use the AnyLogic Cloud API clients provided by AnyLogic, as they contain methods that simplify navigation through Outputs (such methods are available, for example, for the SingleRunOutputs and MultiRunOutputs JavaScript objects). The Outputs object is an array with each element representing a single output from a run or a series of runs. Note that in the case of multi-run experiments, an element may represent an input that varies across runs. The aggregationType field is a system field that indicates how the results of each run are aggregated.

In the case of a single simulation run, there is no aggregation, and the value of the aggregationType field is IDENTITY. In addition to aggregationType, each element of a top-level array always contains the inputs, outputs, and value fields.
Because there are no varied parameters in a single run, there are no input descriptors, and the inputs field is an empty array in all elements. The outputs field is an array with a single element describing the output: its name, type, units, and value. The value of the descriptor is always null in the descriptor.
The possible values of the type field of an array element are listed below.
The actual value of the output is contained in the value field of the top-level array element as an unparsed JSON string. For more information, see Data conversion.
Although an AnyLogic chart (which may contain multiple data elements) is a single element in the AnyLogic run configuration, its data elements become separate elements in the Cloud API. Therefore, the name of each such item is returned by the API in the following format: <the name of the chart in run configuration outputs>|<the title of the data item in the chart>.
For other AnyLogic outputs, such as explicitly defined datasets, statistics objects, output objects, the name in AnyLogic API outputs is the same as in AnyLogic.

In case of multi-run experiments, such as parameter variation or Monte Carlo, the format of еру outputs becomes more complicated. The aggregationType will be ARRAY, and one of the elements in the top-level array will contain a non-empty input field for the input to be varied.
The unparsed value fields of the output elements are multi-element arrays. The order of the output values in the arrays corresponds to the order of the varied input parameter values.
Single-run output 
[
    {
        "aggregationType": "IDENTITY",
        "inputs": [],
        "outputs": [
            {
                "name": "Queue size stats",
                "type": "STATISTICS_CONTINUOUS",
                "units": null,
                "value": null
            }
        ],
        "value": "{\"type\":\"CONTINUOUS\",\"count\":1375730,\"min\":0.0,\"max\":10.0,\"mean\":0.9915478405530092, ... }"
    },
    {
        "aggregationType": "IDENTITY",
        "inputs": [],
        "outputs": [
          {
              "name": "Total time in system|Total time in system",
              "type": "HISTOGRAM_DATA",
              "units": null,
              "value": null
          }
        ],
        "value": "{\"statistics\":{\"type\":\"DISCRETE\",\"count\":1000897,\"min\":1.6001570096705109, … }"
    },
    {
        "aggregationType": "IDENTITY",
        "inputs": [],
        "outputs": [
            {
                "name": "Utilization|Server utilization",
                "type": "DOUBLE",
                "units": null,
                "value": null
            }
        ],
        "value": "0.500358755897554"
    },
    {
        "aggregationType": "IDENTITY",
        "inputs": [],
        "outputs": [
            {
                "name": "Mean queue size|Mean queue size",
                "type": "DOUBLE",
                "units": null,
                "value": null
            }
        ],
        "value": "0.9915478375701102"
    }
]
Multi-run output 
[ 
    {
        "aggregationType": "ARRAY",
        "inputs": [],
        "outputs": [
            {
                "name": "Queue size stats",
                "type": "STATISTICS_CONTINUOUS",
                "units": null,
                "value": null
            }
        ],
        "value": "[{\"count\":1335978,\"min\":0.0,\"max\":10.0,\"mean\":0.9860041083277306,\"variance\":0.07920717342721317, ... }]"
    }, 
    {
        "aggregationType": "ARRAY",
        "inputs": [],
        "outputs": [
            {
                "name": "Total time in system|Total time in system",
                "type": "HISTOGRAM_DATA",
                "units": null,
                "value": null
            }
        ],
        "value": "[{\"statistics\":{\"type\":\"DISCRETE\",\"count\":999206,\"min\":1.4401413087034598, ... }]"
    },
    {
        "aggregationType": "ARRAY",
        "inputs": [],
        "outputs": [
            {
                "name": "Utilization|Server utilization",
                "type": "DOUBLE",
                "units": null,
                "value": null
            }
        ],
        "value": "[0.4497779714401299,0.4750782325123417,0.500358755897554]"
    },
    {
        "aggregationType": "ARRAY",
        "inputs": [],
        "outputs": [
            {
                "name": "Mean queue size|Mean queue size",
                "type": "DOUBLE",
                "units": null,
                "value": null
            }
        ],
        "value": "[0.9860040848956356,0.9877473693031751,0.9915478375701102]" 
    },
    {
        "aggregationType": "ARRAY",
        "inputs": [
            {
                "name": "Mean service time",
                "type": "FIXED_RANGE_DOUBLE",
                "units": null,
                "value": "{\"min\":\"1.8\",\"max\":\"2\",\"step\":\"0.1\"}"
            }
        ],
        "outputs": [],
        "value": "[[1.8],[1.9],[2.0]]"
    }
]

Run Request

The Run Request object contains the type of experiment and the full list of inputs. It does not contain a reference to the model version, which is passed as a part of the request URL.
The value of an input is always a string, which may contain unparsed JSON: for example, to describe a range.
Simulation experiment 
{
    "experimentType": "SIMULATION",
    "inputs": [
        {
            "name": "{STOP_MODE}",
            "type": "STRING",
            "units": null,
            "value": "STOP_MODE_AT_TIME"
        },
        {   "name": "{START_TIME}",
            "type": "DOUBLE",
            "units": "SECOND",
            "value": "0"
        },
        {
            "name": "{STOP_TIME}",
            "type": "DOUBLE",
            "units": "SECOND",
            "value": "1000000"
        },
        {
            "name": "{START_DATE}",
            "type": "DATE_TIME",
            "units": null,
            "value": "2019-05-15T00:00"
        },
        {
            "name": "{STOP_DATE}",
            "type": "DATE_TIME",
            "units": null,
            "value": "2019-05-26T13:46:40"
        },
        {
            "name": "{MAX_MEMORY_MB}",
            "type": "INTEGER",
            "units": null,
            "value": "512"
        },
        {
            "name": "Arrival rate",
            "type": "DOUBLE",
            "units": null,
            "value": "1"
        },
        {
            "name": "Mean service time",
            "type": "DOUBLE",
            "units": null,
            "value": "2"
        },
        {
            "name": "Server capacity",
            "type": "INTEGER",
            "units": null,
            "value":  5
        },
        {
            "name": "Check failure probability",
            "type": "DOUBLE",
            "units": null,
            "value": "0.2"
        },
        {
            "name": "{RANDOM_SEED}",
            "type": "LONG",
            "units": null,
            "value": "1"
        }
    ]
}
Parameter variation experiment 
{
    "experimentType": "PARAMETER_VARIATION",
    "inputs": [
        {
            "name": "{STOP_MODE}",
            "type": "STRING",
            "units": null,
            "value": "STOP_MODE_AT_TIME"
        }, 
        {
            "name": "{START_TIME}",
            "type": "DOUBLE",
            "units": "SECOND",
            "value": "0"
        },
        {
            "name": "{STOP_TIME}",
            "type": "DOUBLE",
            "units": "SECOND",
            "value": "1000000"
        },
        {
            "name": "{START_DATE}",
            "type": "DATE_TIME",
            "units": null,
            "value": "2019-05-15T00:00"
        },
        {
            "name": "{STOP_DATE}",
            "type": "DATE_TIME",
            "units": null,
            "value": "2019-05-26T13:46:40"
        },
        {
            "name": "{MAX_MEMORY_MB}",
            "type": "INTEGER",
            "units": null,
            "value": "512"
        },
        {
            "name": "Arrival rate",
            "type": "DOUBLE",
            "units": null,
            "value": "1"
        },
        {
            "name": "Mean service time",
            "type": "FIXED_RANGE_DOUBLE",
            "units": null,
            "value": "{ \"min\" : 1.8 , \"max\" : 2 , \"step\" : 0.1 }" 
        },
        {
            "name": "Server capacity",
            "type": "INTEGER",
            "units": null,
            "value":  5
        },
        {
            "name": "Check failure probability",
            "type": "DOUBLE",
            "units": null,
            "value": "0.2"
        },
        {
            "name": "{RANDOM_SEED}",
            "type": "LONG",
            "units": null,
            "value": "1"
        }
    ]
}

Experiment Results Request

The Experiment Results Request object contains the type of experiment, the full list of inputs, and the list of required outputs. The latter is a string form of the Outputs object with empty values. 
{
    "experimentType": "SIMULATION",
    "inputs": [
        {
            "name": "{STOP_MODE}",
            "type": "STRING",
            "units": null,
            "value": "STOP_MODE_AT_TIME"
        },
        {
            "name": "{START_TIME}",
            "type": "DOUBLE",
            "units": "SECOND",
            "value": "0"
        },
        {
            "name": "{STOP_TIME}",
            "type": "DOUBLE",
            "units": "SECOND",
            "value": "1000000"
        },
        {
            "name": "{START_DATE}",
            "type": "DATE_TIME",
            "units": null,
            "value": "2019-05-15T00:00"
        },
        {
            "name": "{STOP_DATE}",
            "type": "DATE_TIME",
            "units": null,
            "value": "2019-05-26T13:46:40"
        },
        {
            "name": "{MAX_MEMORY_MB}",
            "type": "INTEGER",
            "units": null,
            "value": "512"
        },
        {
            "name": "Arrival rate",
            "type": "DOUBLE",
            "units": null,
            "value": "1"
        },
        {
            "name": "Mean service time",
            "type": "DOUBLE",
            "units": null,
            "value": "2"
        },
        {
            "name": "Server capacity",
            "type": "INTEGER",
            "units": null,
            "value":  5
        },
        {
            "name": "Check failure probability",
            "type": "DOUBLE",
            "units": null,
            "value": "0.2"
        },
        {
            "name": "{RANDOM_SEED}",
            "type": "LONG",
            "units": null,
            "value": "1"
        }
    ],
    "outputs": "[{\"aggregationType\":\"IDENTITY\",\"inputs\":[],\"outputs\":[{\"name\":\"Queue size\"}]}]"
}

Experiment Run

The Experiment Run object contains the unique run ID, the model version ID, the inputs, the run status, and the message containing unparsed JSON with information about the run and can be empty.
The outputs field of Experiment Run is always empty. 
{
    "id": "Ao7KEYv76pyqZFf6QetmAg6InFuJoJMj1WbYaSm17wo",
    "inputs": [
        {
            "name": "{STOP_MODE}",
            "type": "STRING",
            "units": null,
            "value": "STOP_MODE_AT_TIME"
        },
        {
            "name": "{START_TIME}",
            "type": "DOUBLE",
            "units": "SECOND",
            "value": "0"
        },
        {
            "name": "{STOP_TIME}",
            "type": "DOUBLE",
            "units": "SECOND",
            "value": "1000000"
        },
        {
            "name": "{START_DATE}",
            "type": "DATE_TIME",
            "units": null,
            "value": "2019-05-15T00:00"
        },
        {
            "name": "{STOP_DATE}",
            "type": "DATE_TIME",
            "units": null,
            "value": "2019-05-26T13:46:40"
        },
        {
            "name": "{MAX_MEMORY_MB}",
            "type": "INTEGER",
            "units": null,
            "value": "512"
        },
        {
            "name": "Arrival rate",
            "type": "DOUBLE",
            "units": null,
            "value": "1"
        },
        {
            "name": "Mean service time",
            "type": "DOUBLE",
            "units": null,
            "value": "2"
        },
        {
            "name": "Server capacity",
            "type": "INTEGER",
            "units": null,
            "value": "5"
        },
        {
            "name": "Check failure probability",
            "type": "DOUBLE",
            "units": null,
            "value": "0.2"
        },
        {
            "name": "{RANDOM_SEED}",
            "type": "LONG",
            "units": null,
            "value": "1"
        }
    ],
    "message": "{\"title\":null,\"total\":100,\"finishedTasks\":1,\"totalTasks\":1,\"subRuns\":[]}",
    "modelVersionId": "def089c4-96a3-40f2-aefb-de1af471fe2f",
    "outputs": null,
    "status": "COMPLETED"
}

Animation SVG Run Info

The Animation SVG Run Info object is returned in response to starting a model run with animation. It contains the native dimensions of the animation window, the simulation speed, the URL of the node where the simulation is running, and other information. 
{
    "animationHeight": 600,
    "animationSpeed": 10,
    "animationWidth": 1000,
    "experimentRunId": "fbc6a1d8-fa08-4a5c-a171-4631657c1aa7",
    "modelUuid": "493e6789-acf7-4dac-971d-325cb508ea39",
    "restUrl": "b0cc221b-8217-474b-af18-c2d07753187b/",
    "sessionUuid": "b0cc221b-8217-474b-af18-c2d07753187b",
    "version": "8.5.0"
}

Input types

The input type is a string constant. Possible values:
"STRING"
"DOUBLE"
"INTEGER"
"LONG"
"DATE_TIME"
"BOOLEAN"
"RANDOM_DOUBLE"
"RANDOM_INTEGER"
"RANDOM_BOOLEAN"
"FIXED_RANGE_DOUBLE"
"FIXED_RANGE_INTEGER"
"FIXED_RANGE_LONG"
"FULL_RANGE_BOOLEAN"
"INPUT_FILE"

Units

The unit is a string constant. It can be null. Other possible types:
"MILLISECOND"
"SECOND"
"MINUTE"
"HOUR"
"DAY"
"WEEK"
"MONTH"
"YEAR"
"MILLIMETER"
"CENTIMETER"
"METER"
"KILOMETER"
"INCH"
"FOOT"
"YARD"
"MILE"
"NAUTICAL_MILE"
"SQ_MILLIMETER"
"SQ_CENTIMETER"
"SQ_METER"
"SQ_KILOMETER"
"SQ_INCH"
"SQ_FOOT"
"SQ_YARD"
"SQ_MILE"
"SQ_NAUTICAL_MILE"
"PER_MILLISECOND"
"PER_SECOND"
"PER_MINUTE"
"PER_HOUR"
"PER_DAY"
"PER_WEEK"
"PER_MONTH"
"PER_YEAR"
"MPS"
"KPH"
"FPS"
"FPM"
"MPH"
"KN"
"MPS_SQ"
"FPS_SQ"
"LITER"
"OIL_BARREL"
"CUBIC_METER"
"KILOGRAM"
"TON"
"LITER_PER_SECOND"
"OIL_BARREL_PER_SECOND"
"CUBIC_METER_PER_SECOND"
"KILOGRAM_PER_SECOND"
"TON_PER_SECOND"
"TURN"
"RADIAN"
"DEGREE"
"RPM"
"RAD_PER_SECOND"
"DEG_PER_SECOND"

Output types

The output type is a string constant. Possible values:
"STRING"
"DOUBLE"
"INTEGER"
"LONG"
"DATE_TIME"
"BOOLEAN"
"DATA_SET"
"STATISTICS_DISCRETE"
"STATISTICS_CONTINUOUS"
"HISTOGRAM_DATA"
"HISTOGRAM_2D_DATA"
"MODEL_OUTPUT_NAME"
"OUTPUT_FILE"
How can we improve this article?
We use cookies to give you the best online experience, including personalized content, advertising, and web analytics. You can reject cookies by changing your browser settings. To learn more about the cookies we use, see our Cookie Policy.