How to run a Summit model via web request
Every model you create and host with Summit has its own API signature (argument set) that you define.
For example, if you create a model:
# something very interesting
"livestock": =1<sheep>
"hay": =2<bales>
# more fun with farm modeling
When published as an API, this model will take two querystring arguments: sheep
and bales
(livestock
and hay
are the event names).
These arguments should be sent to your model using the parameters
portion of the request body:
{
"parameters": {
"sheep": 3,
"bales": 1
}
Any arguments omitted from the body will use the default values coded into your SEL. In this case, 2 for bales
and 1 for sheep
.
Input Data (Parameters)
To get a list of all of the parameters your model takes, you can make a single GET
request to your model's primary endpoint with an empty request body.
Method | GET |
Endpoint | https://api.usesummit.com/v1/:organization_slug/:external_id/:app_slug |
Example | <https://api.usesummit.com/v1/oldmacdonald/4a74d7/eieio/ |
This will return the full list of parameters and metadata about those parameters.
{'options': {'resolution': 'month'},
'parameters': [{'default_value': '1',
'description': 'The number of rams and ewes located here.',
'display_name': 'Sheep',
'format': 'number',
'maximum_value': None,
'meta': {},
'minimum_value': 0,
'name': 'sheep',
'raw_default_value': 1,
'type': 'free',
'value_choices': None},
{'default_value': '2',
'description': 'Quantity of bound up cylindrical hays.',
'display_name': 'bales',
'format': 'number',
'maximum_value': 2000,
'meta': {},
'minimum_value': 0,
'name': 'bales',
'raw_default_value': 2,
'type': 'free',
'value_choices': None}],
...
This can allow you to build your own dynamic input UI's that take these parameters as input fields with labels and form validation.
Response Data
What does a model return? If you look at the bottom of the IDE in Summit (with a model loaded on the canvas), you'll notice three views: Grid
, Data
, and Log
.
View | Contents | Use-cases |
---|---|---|
Grid | Shows the subset of model output found in the results attribute of the response. Optionally includes headers that represent time intervals. These are returned under groups . | Forecasts, Simulations |
Data | Shows the subset of model output found in the data attribute of the response. | Data Transformations, Summarizations, Text |
Log | Shows all of the times and values for the events of your model as they occurred, in execution order. | Scheduling, Predictions, Time Estimates |
Each of these data sets is available over an API call to your model's endpoint. Which of these you retrieve is up to you, and depends on the type of model you're building and your intended use-case. Our goal is to provide you with flexibility in terms of response structure so you can spend less time parsing data and more time integrating the fruits of your work into other applications.
Companion Apps
The easiest way to start using your model externally is to install one of our companion apps in your favorite platform. These apps make it easy to select a model to run and fetch the best slice of model output based on your use-case. Summit's companion app in Zapier is called "Models by Summit", and is currently in private beta. If you use a platform where you'd like to see a Summit companion app, or if you'd like to build one, check out our Integrating with Summit page.
Grid - Full
Method | POST |
Endpoint | https://api.usesummit.com/v1/:organization_slug/:external_id/:app_slug |
Example | <https://api.usesummit.com/v1/lovely-realty/9a70d7/mortgage-model/ |
The minimum request body for this endpoint is the parameters
set:
{
"parameters": {
"mortgage": "500000",
"downpayment": "100000"
}
}
You may optionally pass in options
for start
and end
date as ISO-formatted timestrings:
{
"parameters": {
"mortgage": "500000",
"downpayment": "100000"
},
"options": {
"start": "2025-01-01T00:00:00.000Z"
}
}
The response to this endpoint contains the largest amount of data: the full table shown under the Grid
tab in the IDE:
This data set is useful when you want the entire payload of time-based analysis produced by a forecast or simulation, including metrics. As such, this is a popular data set to use for composing charts and graphs.
In the Endpoints screen of the Summit product, you will see this endpoint referred to as Kitchen Sink
because it also includes the data that's available through the Data
endpoint.
When you absolutely must have everything and aren't afraid of parsing or wading through the data, choose this one.
Grid - Single Column
Sometimes less is more, and working with the entire gridded data set is too much. For these situations, you can slice the grid by choosing the column of output you'd like to fetch. This is done using the output
argument of the request body:
{
"parameters": {
"max_run_count": "0",
"end_date": "",
"minute": "59",
"hour": "23",
"business_days_prior": "0"
},
"output": {
"__experimental_flatten": -1
}
}
Notice the __experimental_flatten
argument. This allows you to choose the index of the column you'd like to pull from the grid. -1
is the last column, which is useful for grabbing the last slice of a time series model, like a forecast. "What are the values at the end of the forecast?" This endpoint is a shortcut to fetching that slice of data, for example, the final year of a mortgage, or the last month of a financial forecast.
Data
Method | POST |
Endpoint | https://api.usesummit.com/beta/:organization_slug/:external_id/:app_slug/data |
Example | <https://api.usesummit.com/beta/acme-corp/9a70d7/customer-tickets/data |
The data
endpoint returns what appears in the Data
tab of the Summit IDE, and the data
attribute of the full model response.
This slice of model output is useful when the purpose of the model is data transformation — or, specifically, whatever data is being sent to a Response Data event in the model.
Offering this as a dedicated endpoint makes it easy to ingest this output, which is always sent as a JSON list that contains one or more nested objects or lists.
The input to the Data
endpoint is the parameters set.
Log
Method | POST |
Endpoint | https://api.usesummit.com/beta/:organization_slug/:external_id/:app_slug/data |
Example | <https://api.usesummit.com/beta/acme-corp/9a70d7/customer-tickets/log |
The Log
endpoint returns a list of all of the event executions in a model, and is useful for returning the results of a simulation, where timing is the answer (scheduling or estimated times of completions, for example).
The output of the log endpoint is a list of timestamps with robust metadata for each moment:
[
{
"id": "string",
"date": "string",
"timestamp": "number",
"sel": "string",
"event": "string",
"pretty_date": "string",
"pretty_time": "string",
"pretty_day_of_week": "string",
"pretty_day_of_week_index": "number",
"date_year": "number",
"date_month": "number",
"date_day": "number",
"time_hour": "number",
"time_minute": "number",
"time_second": "number",
"previous_date": "string",
"previous_timestamp": "number",
"previous_delta": "number",
"next_date": "string",
"next_timestamp": "number",
"next_delta": "number",
"since_start": "number",
"until_end": "number"
},
...
]
This is useful for building calendars, or apps that involve setting expectations and communicating around those timings.