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:

• GET
  • View Variables and Operations for a Run
  • View Variables and Operations for a Model

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

• Introspect record

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:

• 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

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:

• 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

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, 
    ]
}