AnyLogic
Expand
Font size

Cloud REST API

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

In Private Cloud, the address would be as follows: <your Private Cloud instance address>/api/open/8.5.0.

To send a request to the Cloud REST API, you need to supply it with 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. For some requests, objects in the request body are necessary. These are described in the Data model section.

Endpoints

Endpoint Description
GET /models Returns the array of all models of the user (the API key owner), that is, the models where the user has either the developer or user permissions.
GET /models/<model id> Returns the model with the given id.
GET /models/name/<model name> Returns the model with the given name.
GET /models/<model id>/versions/number/<version number> Returns the model version with the given number (version numbering starts from 1).
GET /models/<model id>/versions/<version id> Returns the model version with the given ID.
GET /versions/<version id>/experiments Returns the array of experiments created for the given model version.
POST /versions/<version id>/runs Requests to execute a simulation run with the inputs contained in the run request. This will result in a real new simulation only if such run has not been performed yet. Returns Experiment Run, but does not wait for 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 provided 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 containing the status of the run. Use it to query the run state.
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 given id according to the provided outputs template (so that you can control which data you will receive). If the run has not been completed, returns 404.
Blank outputs are required in the request body.
POST /versions/<version id>/results Returns the Outputs of a completed run with a given id according to the outputs template provided.
Does not require the run ID.
The experiment result request is required in the request body.
GET /versions/<version id>/runs/<run id>/progress Returns the experiment run state which contains the status and details of the run (which may be already completed or not).
POST /versions/<version id>/runs/animation Starts 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 has been created.
The run request is required in the request body.

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

Data model

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

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

Each model can have multiple versions. Experiments are executed 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 with each model version.

AnyLogic Cloud: Data model

Model

Model is a simple object with a unique ID, name, description, array of version ids, and a public/not public flag.
{
    "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 full information about the model inputs, outputs, and dashboard configuration in its experimentTemplate field.
The inputs array of this object contains the system inputs of the model: {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 that particular model version. Given that, the values of these fields are always null.
The dashboard configuration is irrelevant from the API user viewpoint, 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 saved 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 the input of the range type ("FIXED_RANGE_INTEGER") it is an unparsed JSON string that contains the min, max, and step fields.
Possible values of the type field are listed below. The unit field can contain 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 Cloud clients provided by AnyLogic, since 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 of a run or a series of runs. Note that in case of multi-run experiments, an element can represent an input varied across the runs. The aggregationType field is a system field that tells how the results of individual runs are aggregated.

In case of a single simulation run, there is no aggregation, and the value of the aggregationType field is IDENTITY. Besides aggregationType, each element of a top-level array always contains the inputs, outputs, and value fields.
As there are no varied parameters in a single run, there are no input descriptors and the inputs field is an empty array in all items. 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 (possibly, containing multiple data items) is a single item in the AnyLogic run configuration, its data items become separate items in the Cloud API. Given that, each such item’s name 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 items in the top-level array will contain a non-empty input field for the input that is being varied.
The unparsed value fields of the output items are arrays with multiple elements. The sequence of the output values in the arrays corresponds to the sequence 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 blank 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 (see Experiment Run State) 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"
}

Experiment Run State

The Experiment Run State object comes in response to a progress request. It contains the status of the run and the message field with the unparsed JSON structure with the run progress details:
{
    "message": "{\"title\":null,\"total\":52,\"finishedTasks\":0,\"totalTasks\":1,\"subRuns\":[]}",
    "status": "RUNNING"
}
To obtain the completed fraction of the run, you can call JSON.parse( <experiment run state>.message ).total;.
The status of a run can be:
  • "FRESH" — created, not yet started
  • "RUNNING" — currently being executed
  • "COMPLETED" — successfully completed, results are available
  • "FAILED" — execution failed
  • "STOPPED" — cancelled before completion by the user (via the UI or API)
For a completed run, the message field may be an empty string:
{
    "message": "",
    "status": "COMPLETED"
}
For a multiple run experiment, Experiment Run State will look like this:
{
    "message": "{\"title\":null,\"total\":47,\"finishedTasks\":0,\"totalTasks\":11, ... }",
    "status": "RUNNING"
}
And if you parse the message field, the structure will be:
{
    "finishedTasks": 0,
    "subRuns": [
        {
            "title": null,
            "total": 42,
            "finishedTasks": 2,
            "totalTasks": 5,
            "subRuns": []
        },
        {
            "title": null,
            "total": 42,
            "finishedTasks": 2,
            "totalTasks": 5,
            "subRuns": []
        }
    ],
    "title": null,
    "total": 47,
    "totalTasks": 11
 }
The subRuns field contains information about the batches of individual runs comprising the experiment.

Animation SVG Run Info

The Animation SVG Run Info object comes in response to starting 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

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

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

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"
How can we improve this article?