Model Variable API

The Model Variable API allows you to view and update the values of model variables for particular runs.

Runs are stored both in memory on the Epicenter servers and in the Epicenter backend database. Updating the value of a variable automatically brings the run into memory, if it wasn't already there. See more information on run persistence.

Variables are queued for persisting from memory to the database if a model operation is called, AND that operation includes an explicit save of the variables (record for a Julia, Python, or R model). The frequency of the queue processing is approximately every 30 seconds.

The Model Variable API supports the following methods:

GET
PATCH
- Update the values of variables for one run
OPTIONS

For GET requests, the Model Variable API returns data structures containing variable names and values:

Variable Response examples

GET

You can retrieve the current value of any model variable using the Model Variable API GET method.

Read one variable from one run

When reading from one run, if the run is in memory, the variable is retrieved immediately. If the run is not currently in memory, it is replayed and then the variable is retrieved.

Method: GET

URI:

/v2/model/variable/{run id}/{variable name}

Headers:

Authorization: Bearer{access token}
- This can be either the user access token of any user (team member or end user) with access to the run, or the project access token for the project.

Body: None

Return Status:

200: Successful response, variable retrieved
400: Invalid variable name
404: Invalid run id

Return Body: The variable value.

Example (string):

curl -G \
    'https://api.forio.com/v2/model/variable/00000152fbfbeae5d4e225640aebaef9a270/sample_string' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \

Example Response:

"Hello World"

Example (object):

curl -G \
    'https://api.forio.com/v2/model/variable/00000152fbfbeae5d4e225640aebaef9a270/results' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \

Example Response:

{
    "max_profit": 914,
    "mean_profit": -753,
    "min_profit": -2210,
    "std_dev_profit": 427
}

Example (field within object):

curl -G \
    'https://api.forio.com/v2/model/variable/00000152fbfbeae5d4e225640aebaef9a270/results.max_profit' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \

Example Response:

Notes:

If the run is in memory, the variable is retrieved immediately.
If the run is not currently in memory, it is replayed and then the variable is retrieved. (Therefore, depending on the model and the replay configuration, the value of the variable may or may not be the same as it was last time you retrieved it!)
The variable name can include hard-coded array indices (name[index]) or object fields (name.field) if desired. Array indices are modeling-language dependent.
If the variable is in a separate scope, that scope must be included in the variable name in the URI (myModule.sample_string).
For arrayed variables in Vensim models, the time step is the last index (name[index, time step]). (Note that for arrayed constants in Vensim models, there is no time index.)

Read one variable from many runs

When reading from many runs, all information is pulled from the database, regardless of whether the run is also currently in memory.

As a consequence, only variables that have been explicitly saved to the database are available for query using this method. (Variables are saved to the database using Epicenter.record() or similar, see Writing your model.)

Method: GET

URI:

/v2/model/variable/;id={run id};id={run id}/{variable name}

Headers:

Authorization: Bearer{access token}
- This can be either the user access token of any user (team member or end user) with access to the run, or the project access token for the project.

Body: None

Return Status:

200: Successful response, variables retrieved
400: Invalid variable, or variable not saved to database in model
404: Invalid run id

Return Body: An array of JSON objects, each one including the run id and variable value.

Example:

curl -G \
    'https://api.forio.com/v2/model/variable/;id=00000152fbfbeae5d4e225640aebaef9ab18;id=00000152fbfbeae5d4e225640aebaef9ab1d/sample_int' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \

Example Response:

[
    {
        "run": "00000152fbfbeae5d4e225640aebaef9ab18",
        "variables": 10
    },
    {
        "run": "00000152fbfbeae5d4e225640aebaef9ab1d",
        "variables": 15
    }
]

Notes:

When reading from many runs, all information is pulled from the database, regardless of whether the run is also currently in memory. As a consequence, only variables that have been explicitly saved to the database are available for query using this method. (Variables are saved to the database using Epicenter.record() or similar, see Writing your model.)
Note that the variable name may NOT include hard-coded array indices (name[index]) or object fields (name.field); only the complete variable is available when you are reading from many runs.
- There is one exception to this, which is Vensim variables: these may include the time index.
If the variable is in a separate scope, that scope must be included in the variable name in the URI (myModule.sample_string).

Read many variables from one run

When reading from one run, if the run is in memory, the variable is retrieved immediately. If the run is not currently in memory, it is replayed and then the variable is retrieved.

Method: GET

URI:

/v2/model/variable/{run id}?name={variable name}&name={variable name}

Headers:

Authorization: Bearer{access token}
- This can be either the user access token of any user (team member or end user) with access to the run, or the project access token for the project.

Body: None

Return Status:

200: Successful response, variables retrieved
400: Invalid variable (even if only one variable is invalid)
404: Invalid run id

Return Body: A JSON object containing the variable names and values.

Example:

curl -G \
    'https://api.forio.com/v2/model/variable/00000152fbfbeae5d4e225640aebaef9a2fa?name=sample_string&name=sample_int' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \

Example Response:

{
    "sample_string": "Hello World!",
    "sample_int": 10
}

Notes:

If the run is in memory, the variable is retrieved immediately.
If the run is not currently in memory, it is replayed and then the variable is retrieved. (Therefore, depending on the model and the replay configuration, the value of the variable may or may not be the same as it was last time you retrieved it!)
The variable name can include hard-coded array indices (name[index]) or object fields (name.field) if desired. Array indices are modeling-language dependent.
If the variable is in a separate scope, that scope must be included in the variable name in the URI (myModule.sample_string).
For arrayed variables in Vensim models, the time step is the last index (name[index, time step]). (Note that for arrayed constants in Vensim models, there is no time index.)

Read many variables from many runs

When reading from many runs, all information is pulled from the database, regardless of whether the run is also currently in memory.

Method: GET

URI:

/v2/model/variable/;id={run id};id={run id}/?name={variable name}&name={variable name}

Headers:

Authorization: Bearer{access token}
- This can be either the user access token of any user (team member or end user) with access to the run, or the project access token for the project.

Body: None

Return Status:

200: Successful response, variables retrieved
400: Invalid variable, or variable not saved to database in model
404: Invalid run id

Return Body: An array of JSON objects, each one including the run id and an object with all of the variable names and values.

Example:

curl -G \
    'https://api.forio.com/v2/model/variable/;id=00000152fbfbeae5d4e225640aebaef9ab82;id=00000152fbfbeae5d4e225640aebaef9ab87/?name=sample_int&name=sample_array' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \

Example Response:

[
    {
        "run": "00000152fbfbeae5d4e225640aebaef9ab82",
        "variables": {
            "sample_int": 10,
            "sample_array": [
                2,
                4,
                6,
                8
            ]
        }
    },
    {
        "run": "00000152fbfbeae5d4e225640aebaef9ab87",
        "variables": {
            "sample_int": 15,
            "sample_array": [
                1,
                3,
                5,
                7
            ]
        }
    }
]

Notes:

When reading from many runs, all information is pulled from the database, regardless of whether the run is also currently in memory. As a consequence, only variables that have been explicitly saved to the database are available for query using this method. (Variables are saved to the database using Epicenter.record() or similar, see Writing your model.)
Note that the variable name may NOT include hard-coded array indices (name[index]) or object fields (name.field); only the complete variable is available when you are reading from many runs.
- There is one exception to this, which is Vensim variables: these may include the time index.
If the variable is in a separate scope, that scope must be included in the variable name in the URI (myModule.sample_string).

PATCH

You can update the value of any model variable using the Model Variable API PATCH method.

Runs must be in memory in order for you to update variables or call operations on them. Runs are automatically replayed, and brought back into memory, when you attempt to update a model variable.

Update the values of variables for one run

Method: PATCH

URI:

/v2/model/variable/{run id}

Headers:

Content-Type: application/json
Authorization: Bearer{access token}
- This can be either the user access token of any user (team member or end user) with access to the run, or the project access token for the project.

Body: JSON object whose fields are variable names and whose values are the updated variable values, e.g. { "fieldName1": "fieldValue1", "fieldName2": "fieldValue2"}.

Return Status:

200: Successful response, variables updated
400: Invalid variable

Return Body: A JSON array with the variables updated and their current (newly updated) values.

Example:

curl -X PATCH \
    'https://api.forio.com/v2/model/variable/00000152fbfbeae5d4e225640aebaef9abd7' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{"sample_int": 16, "sample_dict[\"day\"]": "tuesday", "sample_array[1]": 300}'

Example Response:

{
    "sample_int": 16,
    "sample_dict[\"day\"]": "tuesday",
    "sample_array[1]": 304
}

Notes:

The variable names can include hard-coded array indices (name[index]) or object fields (name.field) if desired. Array indices are modeling-language dependent.
If the variable is in a separate scope, that scope must be included in the variable name in the URI (myModule.sample_string).
The body of the requst must be valid JSON. Therefore, for boolean variables in Python models,
- You can use boolean values directly: { "sample_bool": true }.
- You can use the Python convention for boolean values only if you pass the string value: { "sample_bool": "True" }.
For arrayed variables in Vensim models, the time step is the last index (name[index, time step]). (Note that for arrayed constants in Vensim models, there is no time index.)
For Vensim "LOOKUP" variables, the Epicenter format is an array. Each array element is itself an array with two elements: the x-y pairs from the original Vensim variable. When using the PATCH method, update the entire Epicenter representation (replace all values); you can change the number of ordered pairs if desired. For example:
- Original Vensim LOOKUP represenation: [(2000,0)-(2010,2)],(2000,1),(2005,.5),(2010,1)
- Epicenter representation: [ [2000,1], [2005,.5], [2010,1] ]
For Vensim models, variables designated as "CONSTANT" or "LOOKUP" variables can only be changed at the start of the simulation run.
For additional examples of working with complex variables (e.g. multidimensional arrays, lists, dicts, etc.), see the specific language pages:

OPTIONS

For any Epicenter API, use the OPTIONS method to view reference information on properties and arguments of that API.

Method: OPTIONS

URI: /v2/model/variable/

Example:

curl -X OPTIONS 'https://api.forio.com/v2/model/variable/'

Data Structure

Variable Response Examples

The GET request for the Model Variable API returns data structures containing variable names and values, and the run id if the request is for variables from multiple runs. The exact structure varies based on the type of GET request.

Example: One variable from one run (See request details)

In this case, only the value of the variable is returned.

Note that this may be simple (e.g. if the variable is scalar):

Or it may be an entire obejct:

{
    "max_profit": 914,
    "mean_profit": -753,
    "min_profit": -2210,
    "std_dev_profit": 427
}

Example: One variable from many runs (See request details)

In this case, an array of JSON objects is returned. Each JSON object includes the run id and the value of the variable for that run:

[
    {
        "run": "00000152fbfbeae5d4e225640aebaef9ab18",
        "variables": 10
    },
    {
        "run": "00000152fbfbeae5d4e225640aebaef9ab1d",
        "variables": 15
    }
]

Field	Required?	Description
`run`	yes	The identifier of the run.
`variables`	yes	The value of the variable for that run.

Example: Many variables from one run (See request details)

In this case, a JSON object is returned. Each JSON object includes the variable names and values:

{
    "sample_string": "Hello World!",
    "sample_int": 10,
    "sample_object":     {
        "max_profit": 914,
        "mean_profit": -753,
        "min_profit": -2210,
        "std_dev_profit": 427
    }
}

Example: Many variables from many runs (See request details)

In this case, an array of JSON objects is returned. Each JSON object includes the run id and a variables object. The variables object includes the variable names and values.

[
    {
        "run": "00000152fbfbeae5d4e225640aebaef9ab82",
        "variables": {
            "sample_int": 10,
            "sample_array": [
                2,
                4,
                6,
                8
            ]
        }
    },
    ... // objects for other runs as requested
]

Field	Required?	Description
`run`	yes	The identifier of the run.
`variables`	yes	An object containing the variable names and values for this run.