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:

{
    "variables": [
        {
            "type": "list",
            "name": "sample_array"
        },
        {
            "type": "customObj",
            "name": "sample_customObj"
        },
        {
            "type": "int",
            "name": "sample_int"
        },
        {
            "type": "dict",
            "name": "sample_dict"
        },
        {
            "type": "str",
            "name": "sample_string"
        }
    ],
    "functions": [
        {
            "name": "advance",        // this operation takes no arguments
            "signature": [ ]
        },
        {
            "name": "updateValue",  // this operation takes one argument
            "signature": [ "val" ]
        }
    ]
}

Notes:

  • This API is available for Python, R, Julia, Vensim, and Powersim. It is not available for SimLang.
  • 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 memroy when you call introspect. See more on Run Persistence.)
  • If this is a Vensim or Powersim run, the request also returns the ranges for all arrayed variables. The format looks like this:

      {
          "ranges": [
              {
                  "indices": [
                      "apples",
                      "oranges",
                      "bananas"
                  ],
                  "name": "range1",
                  "saved": false,
                  "type": "Subscript Range"
              }
          ],
          "variables": [
              {
                  "name": "sampleArrayVar",
                  "saved": false,
                  "subscripts": [
                      "[range1]"  // this sampleArrayVar is over the "range1" range, which is listed above
                  ],
                  "type": "Constant"
              },
              // 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}/{team id}/{model file name}

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:

{
    "variables": [
        {
            "type": "list",
            "name": "sample_array"
        },
        {
            "type": "customObj",
            "name": "sample_customObj"
        },
        {
            "type": "int",
            "name": "sample_int"
        },
        {
            "type": "dict",
            "name": "sample_dict"
        },
        {
            "type": "str",
            "name": "sample_string"
        }
    ],
    "functions": [
        {
            "name": "advance",        // this operation takes no arguments
            "signature": [ ]
        },
        {
            "name": "updateValue",  // this operation takes one argument
            "signature": [ "val" ]
        }
    ]
}

Notes:

  • This API is available for Python, R, Julia, Vensim, and Powersim. It is not available for SimLang.
  • In the URI, the Account ID is the Team ID (for team projects) or User ID (for personal projects).
  • If this is a Vensim or Powersim run, the request also returns the ranges for all arrayed variables. The format looks like this:

      {
          "ranges": [
              {
                  "indices": [
                      "apples",
                      "oranges",
                      "bananas"
                  ],
                  "name": "range1",
                  "saved": false,
                  "type": "Subscript Range"
              }
          ],
          "variables": [
              {
                  "name": "sampleArrayVar",
                  "saved": false,
                  "subscripts": [
                      "[range1]"  // this sampleArrayVar is over the "range1" range, which is listed above
                  ],
                  "type": "Constant"
              },
              // 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
variables yes An array of objects, representing the variables accessible to the API calls for this model.
variables[N].name yes The name of the variable.
variables[N].type yes The type of the variable. Available types depend on the modeling language.

In Python, the name and type are also reported for user-defined classes:
  • If the class has a metaclass, then the type of the class is the metaclass
  • If the class has no metaclass and inherits from object either implicitly (Python 3) or explicitly (Python 2), then the type of the class is type
  • If the class does not inherit from anything (only possible in Python 2), then the type of the class is classobj
functions yes An array of objects, representing the operation (functions or methods) accessible to the API calls for this model.
functions[N].name yes The name of the operation.
functions[N].signature no An array of the names of the arguments to this operation. If the operation takes no arguments, this element is still present: it is an empty array.

Note: When Python models include (imported) functions implemented in C, those functions will not have a signature returned.
ranges no An array of objects, representing the ranges or indices for Vensim array variables. Only relevant for Vensim and Powersim.
ranges[N].indices no An array of the (string) names of the range values for the Vensim variable.
ranges[N].name no The name of the range.
ranges[N].saved no Always false.
ranges[N].type no Always Subscript Range.


Example Introspect Record

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

{
    "variables": [
        {
            "type": "list",
            "name": "sample_array"
        },
        {
            "type": "customObj",
            "name": "sample_customObj"
        },
        {
            "type": "int",
            "name": "sample_int"
        },
        {
            "type": "dict",
            "name": "sample_dict"
        },
        {
            "type": "str",
            "name": "sample_string"
        }
    ],
    "functions": [
        {
            "name": "advance",        // this operation takes no arguments
            "signature": [ ]
        },
        {
            "name": "updateValue",  // this operation takes one argument
            "signature": [ "val" ]
        }
    ]
}