Skip to content

Runs overview

Learn how to start and manage runs with your tool of choice.

  • CLI: the Nextmv Command Line Interface (CLI).
  • Python SDK: a Software Development Kit (SDK) for Python developers.
  • Cloud API: an HTTP API for developers to integrate with the Nextmv platform.

A run is a single execution of an app against an instance. It is the basic functionality encompassed of receiving an input, running the app, and returning an output. Runs work the same for both custom and subscription apps.

There are two recommended methods for running an app:

  1. Using polling.
  2. Using webhooks.

If not needed, you can also cancel a run.

Lastly, it is possible to track external runs that happened outside of the Nextmv Cloud environment. You can read more in the external runs page.

Polling

The polling method is the most common way to execute a run. It involves the following steps:

  1. Submit a run request with the input (payload) and options (if desired). A run_id is returned.

  2. Sleep for an appropriate amount of time.

  3. Get the run information using the run_id. In the metadata, look for the status_v2 (status) field. The following states indicate that you should stop polling:

    • succeeded: the run completed and you can retrieve the run results.
    • failed: the run did not complete and you can retrieve the run error.
    • canceled: the run was canceled.

    On the other hand, the following states indicate that you should continue polling:

    • running: the run is still in progress.
    • queued: the run is waiting to be executed.

    Each time you check for the run status (poll), you should exponentially increase the time between polls. Additionally, you should add a small random jitter to avoid thundering herd problems. This is called exponential backoff with jitter. Lastly, we recommend you set a maximum number of retries and a timeout.

  4. Once you are done polling, use the run_id to retrieve the run results or error logs.

Options

Decision models can usually be run with parameters (options) that control the behavior of said model. For example, setting the solver's time limit or the number of threads to use. Nextmv uses Command-Line (CLI) flags to recognize options that can be passed to a run.

Please consider the following when using options:

  1. Your application must be designed to accept CLI flags.
  2. When you execute a run, Nextmv will pass the options to your application as CLI flags. For example, if you set the option time_limit to 10, Nextmv will pass the flag -time_limit=10 to your application.

We recommend that you browse our community apps, specifically the README.md and app.yaml files, to see how different applications use CLI flags to control the behavior of their models.

When starting any remote run on the Nextmv platform, the options will be applied in the following order, with each set overriding the last if a value is provided.

  1. Version: via app.yaml manifest configuration.options property.
  2. Instance: according to the instance configurations.
  3. Run Configuration: the actual options provided when starting the run.

If you need a different format from the default one (-{{name}}={{value}}), you may customize it with the configuration.options.format field in the app.yaml manifest.

Cancel a run

You can cancel a run when it is no longer necessary. To cancel a run, you need the run_id. Runs that are in the following states (given by the status_v2 in the metadata) can be canceled:

  • running: the run is in progress.
  • queued: the run is waiting to be executed.