Run a local Application¶

Reference

Find the reference for the Application class in the technical reference.

A run is a single execution of an app's decision model. It is the basic functionality encompassed of receiving an input, running the app, and returning an output. This how-to guide will walk you through running an app locally.

The recommended method for running an app is using polling.

Here is an example of using the Application.new_run_with_result method, which takes care of all the nuances of polling for you. The Nextmv Python SDK automatically handles polling, file size limits, retries, exponential backoff, jitter, timeouts, and other Nextmv nuances for you.

import nextmv
from nextmv import local

app = local.Application(src="<YOUR_APP_SRC>") # Path to your local app, where the app.yaml manifest is located.

run_result = app.new_run_with_result(
    input={"name": "Patches", "radius": 6378, "distance": 147.6},
    run_options={
        "details": "true",
    },
    polling_options=nextmv.PollingOptions(),  # Customize polling options.
)

nextmv.write(run_result)

Alternatively, you can run the app in steps.

Submit a run request with the input (payload) and options (if desired). A run_id is returned. Use the Application.new_run: creates (submits) a new run and returns the ID (run_id) of the run. With the run_id you can perform other operations, such as getting the run’s metadata, logs, and result. The following example shows how to make a new run.

main.py

from nextmv import local

app = local.Application(src="<YOUR_APP_SRC>") # Path to your local app, where the app.yaml manifest is located.

run_id = app.new_run(
    input={"name": "Patches", "radius": 6378, "distance": 147.6},
    options={
        "details": "true",
    },
)

print(run_id)

$ uv run main.py 

local-rq0pw6sy

Get the status of the run using the Application.run_information method.

main.py

import nextmv
from nextmv import local

app = local.Application(src="<YOUR_APP_SRC>")
run_information = app.run_information(run_id="local-rq0pw6sy")
nextmv.write({"result": run_information.metadata.status_v2})  # Get the status of the run

$ uv run main.py

{
  "result": "succeeded"
}

Once you are done polling, retrieve the run results or error using the run_id. The following example shows how to get the run results using the Application.run_result method.

import nextmv
from nextmv import local

app = local.Application(src="<YOUR_APP_SRC>")
run_result = app.run_result(run_id="local-rq0pw6sy")
nextmv.write(run_result)  # Get the full result of the run.

$ uv run  main.py

{
  "description": "Local run created at 2025-10-03T09:14:49.543398Z",
  "id": "local-au9xnvbj",
  "metadata": {
    "application_id": "/Users/sebastian-quintero/nextmv/github/nextmv-py/nextmv/app-voo59k17",
    "application_instance_id": "",
    "application_version_id": "",
    "created_at": "2025-10-03T09:14:49.543398Z",
    "duration": 1311.6,
    "error": "",
    "input_size": 62.0,
    "output_size": 0.0,
    "format": {
      "input": {
        "type": "json"
      },
      "output": {
        "type": "json"
      }
    },
    "status_v2": "succeeded"
  },
  "name": "local run local-au9xnvbj",
  "user_email": "",
  "console_url": "",
  "synced_run_id": "devint-D6OCps3Ng",
  "synced_at": "2025-10-03T09:15:06.868320Z",
  "output": {
    "options": {
      "details": true
    },
    "solution": {
      "message": "Hello, Patches"
    },
    "statistics": {
      "result": {
        "value": 1.23,
        "custom": {
          "message": "Hello, Patches"
        }
      },
      "schema": "v1"
    },
    "assets": [...]
  }
}

If you are polling for a run, we strongly encourage you to use the methods provided by the SDK that handle polling, retries, exponential backoff, jitter, and timeouts for you:

Application.new_run_with_result: does the same as new_run, but it also polls for the result of the run. This method returns the result of the run, and it is useful for submitting and getting the result in a single call. Using this method is recommended because we have a built-in polling mechanism that handles retries, exponential backoff, jitter, and timeouts.
Application.run_result_with_polling: does the same as run_result, but it also polls for the metadata of the run. This method returns the result of the run, and it is useful for checking the status of the run in a single call.

Run `multi-file` inputs¶

You can use the input_dir_path in the Application.new_run and Application.new_run_with_result methods argument to read inputs from the local filesystem. The following input format are supported:

ContentFormat.MULTI_FILE: one, or more, files. This is the most flexible input format, as it supports all the file formats that have been mentioned previously (JSON, utf-8 encoded text, CSV). In addition, Excel files are supported as well.

Please note the following:

The input_dir_path is the path to a directory containing input files. If specified, the function will package the files in the directory into a tar file and upload it as a large input.
If both input and input_dir_path are specified, input is ignored, and the files in the directory are used instead.

Here is an example of how to run an app with a directory of input files:

import os

import nextmv
from nextmv import local

app = local.Application(src="<YOUR_APP_SRC>")


# Run with MULTI_FILE input.
multi_file_run_id = app.new_run(
    input_dir_path="inputs", # Files are in the "inputs" directory.
)
print(f"MULTI_FILE run ID: {multi_file_run_id}")

List all runs¶

You can list all the runs created in your local app using the Application.list_runs method. This method returns a list of runs, each containing metadata about the run, such as its ID, creation time, duration, status, and more.

from nextmv import local

app = local.Application(src="<YOUR_APP_SRC>")

# List all runs
runs = app.list_runs()
for run in runs:
    print(f"Run ID: {run.id}, Status: {run.status_v2.value}")

You should see an output similar to this one:

Run ID: local-w2ze2sth, Status: succeeded
Run ID: local-80mxxuq8, Status: succeeded
Run ID: local-rq0pw6sy, Status: succeeded

Run logs¶

You can retrieve the logs for a specific run using the Application.run_logs method. This method returns the logs as a string, which can be printed directly to display them in the same format as they are stored locally.

from nextmv import local

app = local.Application(src="<YOUR_APP_SRC>")

# Get the logs for a specific run
logs = app.run_logs(run_id="local-rq0pw6sy")
print(logs)

The logs are retrieved from the .nextmv/runs/{run_id}/logs/logs.log file in your local application directory. If the run does not have any logs or they are empty, the method returns an empty string.

Example output:

$ uv run main.py

2025-10-03T09:14:49.543Z [INFO] Starting run local-rq0pw6sy
2025-10-03T09:14:49.612Z [INFO] Processing input data
2025-10-03T09:14:50.821Z [INFO] Run completed successfully

Run a local Application¶

Run multi-file inputs¶

List all runs¶

Run logs¶

Run `multi-file` inputs¶