forio Toggle navigation

Model Introspect API

The Model Introspect API returns a JSON object listing the variables and operations available in a model.

The Model Introspect API supports the following methods:

The Model Introspect API operates on the following resources / data structures:

GET

View Variables and Operations for a Run

If you already have a run, you can view its variables and operations using the Run ID.


Method: GET

URI: /v2/model/introspect/{run id}

Headers:

Body: None

Return Status:

  • 200: Successful response

Return Body: A JSON object with the functions (operations) and variables available in the model used to create this run.


Example:

curl -G \
    'https://api.forio.com/v2/model/introspect/000001533965543534cd21a606beb8fe8b61' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \

Example Response:

{
  "functions": [
    {
      "signature": [],
      "name": "retFive",  // this operation takes no arguments
      "returnType": null
    },
    {
      "signature": [
        {
          "dataType": null,
          "default": null,
          "name": "val",
          "optional": null
        }
      ],
      "name": "update",  // this operation takes one argument
      "returnType": null
    }
  ],
  "ranges": null,
  "variables": [
    {
      "access": "ALWAYS",
      "dataType": "NUMBER",
      "name": "sample_int",  // one global variable in the model
      "subscripts": null,
      "saved": false
    }
  ]
}

Notes:

  • The Run ID must be for a run in memory. (While a run that is in the database is automatically brought back into memory when you call operations, and optionally, when you get variables, it is NOT brought back into memory when you call introspect. See more on Run Persistence.)
  • If this is a Forio SimLang, Powersim, Stella, or Vensim run, the request also returns the ranges for all arrayed variables. The format looks like this:

      {
          "ranges": [{
              "indices": [
                  "apple",
                  "orange",
                  "banana"
              ],
              "name": "product"
          }],
          "variables": [
               {
                  "access": "NEVER",
                  "dataType": "NUMBER",
                  "name": "Revenue",
                      // Revenue is arrayed over the "product" range
                  "subscripts": [ "product" ], 
                  "saved": false
              }, 
              // other variables in this model
          ],
          "functions": [ 
              // operations available
          ]
      }
    
  • If this is a Forio SimLang run or Powersim run, the ranges for arrayed variables may be explicit (as above), or implicit. For example, if your SimLang declaration is:

      V Sales By Quarter[1..4]
    

    then the format for the introspect record looks like this:

      {
          "ranges": [{
              "indices": [
                  "1",
                  "2",
                  "3",
                  "4"
              ],
              "name": "implicitRange0"
          }],
          "variables": [
               {
                  "access": "ALWAYS",
                  "dataType": "NUMBER",
                  "name": "Sales By Quarter",
                  "subscripts": [ "implicitRange0" ],
                  "saved": false
              }, 
              // other variables in this model
          ],
          "functions": [ 
              // operations available
          ]
      }
    

View Variables and Operations for a Model

Even if you do not have an active run, you can still view its variables and operations by including the name of the model file in your request.


Method: GET

URI:

  • /v2/model/introspect/{account id}/{project id}/{model file name}
  • Python only: /v2/model/introspect/{account id}/{project id}/{model file name}?upwardlyMobile=true|false

Headers:

Body: None

Return Status:

  • 200: Successful response

Return Body: A JSON object with the functions (operations) and variables available in the model used to create this run.


Example:

curl -G \
    'https://api.forio.com/v2/model/introspect/acme/supply_chain_game/model.py' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \

Example Response:

{
  "functions": [
    {
      "signature": [],
      "name": "retFive",  // this operation takes no arguments
      "returnType": null
    },
    {
      "signature": [
        {
          "dataType": null,
          "default": null,
          "name": "val",
          "optional": null
        }
      ],
      "name": "update",  // this operation takes one argument
      "returnType": null
    }
  ],
  "ranges": null,
  "variables": [
    {
      "access": "ALWAYS",
      "dataType": "NUMBER",
      "name": "sample_int",  // one global variable in the model
      "subscripts": null,
      "saved": false
    }
  ]
}

Notes:

  • In the URI, the Account ID is the Team ID (for team projects) or User ID (for personal projects).
  • For Python models only, you can optionally include the parameter ?upwardlyMobile= at the end of the URI. Using true introspects the model using Python 3. Using false introspects the model using Python 2. The default if is false.
  • If this is a Forio SimLang, Powersim, Stella, or Vensim model, the request also returns the enumerated ranges for arrayed variables. The format looks like this:

      {
          "ranges": [{
              "indices": [
                  "apple",
                  "orange",
                  "banana"
              ],
              "name": "product"
          }],
          "variables": [
               {
                  "access": "NEVER",
                  "dataType": "NUMBER",
                  "name": "Revenue",
                  "subscripts": [ "product" ],
                      // Revenue is arrayed over the "product" range
                  "saved": false
              }, 
              // other variables in this model
          ],
          "functions": [ 
              // operations available
          ]
      }
    
  • If this is a Forio SimLang or Powersim model, the ranges for arrayed variables may be explicit (as above), or implicit. For example, if your SimLang declaration is:

      V Sales By Quarter[1..4]
    

    then the format for the introspect record looks like this:

      {
          "ranges": [{
              "indices": [
                  "1",
                  "2",
                  "3",
                  "4"
              ],
              "name": "implicitRange0"
          }],
          "variables": [
               {
                  "access": "ALWAYS",
                  "dataType": "NUMBER",
                  "name": "Sales By Quarter",
                  "subscripts": [ "implicitRange0" ],
                  "saved": false
              }, 
              // other variables in this model
          ],
          "functions": [ 
              // operations available
          ]
      }
    

Data Structure

The Model Introspect API returns an Introspect record.

Introspect record

The Introspect record is returned with any GET request to look up variables and operations for a model.

Field Required? Description
functions yes An array of objects, representing the operation (functions or methods) accessible to the API calls for this model.
functions[N].signature yes An array of the arguments for this model operation. If the operation takes no arguments, this element is still present: it is an empty array.
functions[N].signature.dataType yes The type of this argument for this operation, e.g. NUMBER.
functions[N].signature.default yes The default value for this argument for this operation. Listed as null if there is no default value.
functions[N].signature.name yes The name of the operation.
functions[N].signature.optional yes Whether or not the argument is optional.
functions[N].name yes The name of the operation.
functions[N].returnType yes The type of the return value for this operation, e.g. NUMBER.
ranges yes An array of objects, describing the enumerated ranges for array variables. Only relevant for time-based modeling languages: Vensim, Powersim; otherwise null.
ranges[N].indices no An array of the (string) names of the enumerated range values for the array variable.
ranges[N].name no The name of the range.
variables yes An array of objects, representing the variables accessible to the API calls for this model.
variables[N].access yes Information on when the variable can be updated by an end user. Options are:

  • NEVER if the variable cannot be updated by an end user.
  • BEFORE if the variable can only be updated before the model is advanced (stepped).
  • ALWAYS if the variable can be updated any time after the run is created.
Only relevant for time-based modeling languages: Vensim, Powersim.
variables[N].dataType yes The type of the variable, or the type of the array elements if the variable is an array, e.g. NUMBER. Available types depend on the modeling language.
variables[N].name yes The name of the variable.
variables[N].subscripts yes An array of the names of the ranges that define this array.
variables[N].saved yes Whether the variable is marked save in the Model Context file, that is, whether the varialbe is available after the run is removed from memory and stored in the Epicenter backend database. Only relevant for time-based modeling languages: Vensim, Powersim; otherwise false.


Example Introspect Record

An example Introspect record returned as a response to a GET request:

{
    "functions": [{
        "signature": [{
            "dataType": "NUMBER",
            "default": 1,
            "name": "increment",
            "optional": true
        }],
        "name": "step",
        "returnType": "NUMBER"
    }, {
        "signature": [{
            "dataType": "NUMBER",
            "default": null,
            "name": "time",
            "optional": false
        }],
        "name": "stepTo",
        "returnType": "NUMBER"
    }],
    "ranges": [{
        "indices": [
            "apple",
            "orange",
            "banana"
        ],
        "name": "product"
    }, {
        "indices": [
            "east",
            "west"
        ],
        "name": "region"
    }],
    "variables": [{
            "access": "AFTER",
            "dataType": "NUMBER",
            "name": "Growth Rate",
            "subscripts": null,
            "saved": false
        }, {
            "access": "BEFORE",
            "dataType": "NUMBER",
            "name": "Initial Sales",
            "ranges": [
                "region",
                "product"
            ],
            "saved": false
        }, {
            "access": "NEVER",
            "dataType": "NUMBER",
            "name": "Revenue",
            "subscripts": [
                "region",
                "product"
            ],
            "saved": false
        }, {
            "access": "NEVER",
            "dataType": "NUMBER",
            "name": "Sales",
            "subscripts": [
                "region",
                "product"
            ],
            "saved": false
        },
        ... // other variables, 
    ]
}