Run an app remotely

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. This tutorial will walk you through running an app remotely on Nextmv Cloud. It works the same for both subscription apps and custom apps.

There are several interfaces for running an app:

• Nextmv CLI: use your terminal.
• Python SDK: use Python.
• Cloud API: use the HTTP endpoints.
• Console: use the web interface.

There are two recommended methods for running an app:

1. Using polling.
2. Using webhooks. Go that section for more information.

When a new run is submitted, you can attach it to an existing batch experiment using the batch_experiment_id field. This will ignore existing online experiments attached to the instance (shadow and switchback tests).

You can work with non-json input/output when executing remote runs to your app.

Polling

The polling method is the most common way to check the status of 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_status_v2 in the metadata using the run_id. 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 increase the time between polls. This is called exponential backoff. In addition, you should set a maximum number of retries and a timeout.

4. Once you are done polling, retrieve the run results or error using the run_id.

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 run_status_v2 in the metadata) can be canceled:

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

You can cancel a run using the following methods:

• Nextmv CLI. Use the nextmv app cancel command.

  • Bash
  • Output (Bash)

  nextmv app cancel \
     --app-id "<YOUR-APP-ID>" \
     --run-id "<YOUR-RUN-ID>"
  

  Copy

• Python SDK. Use the Application.cancel_run method.

  • Python

  import os
  
  from nextmv.cloud import Application, Client
  
  client = Client(api_key=os.getenv("NEXTMV_API_KEY"))
  app = Application(client=client, id="<YOUR-APP-ID>")
  app.cancel_run(run_id="<YOUR-RUN-ID>")
  

  Copy

• Cloud API. Use the following endpoint.

  PATCHhttps://api.cloud.nextmv.io/v1/applications/{application_id}/runs/{run_id}/cancel

  Cancel a run that is not yet completed.

  Cancel a run that is not yet completed.

  View API details
  • Bash

  curl -L -X PATCH \
     "https://api.cloud.nextmv.io/v1/applications/$APP_ID/runs/$RUN_ID/cancel" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $NEXTMV_API_KEY"
  

  Copy

Queued runs

When you submit a run, it is placed in a queue. The run will be executed when resources are available. The queue is set at the account level, so you can visualize runs from all applications in the same queue. A run is queued when the status_v2 in the metadata is queued.

To get the account queue you can use the following methods:

• Nextmv CLI. Use the nextmv account queue command.

  • Bash
  • Output (JSON)

  nextmv account queue
  

  Copy

• Python SDK. Use the Account.queue method.

  • Python
  • Output (JSON)

  import json
  import os
  
  from nextmv.cloud import Client
  from nextmv.cloud.account import Account
  
  client = Client(api_key=os.getenv("NEXTMV_API_KEY_PROD"))
  account = Account(client=client)
  queue = account.queue()
  
  print(json.dumps(queue.to_dict(), indent=2))  # Pretty print.
  

  Copy

• Cloud API. Use the following endpoint.

  GEThttps://api.cloud.nextmv.io/v1/account/queue

  List queued and active runs.

  Retrieves a list of queued and active runs.

  View API details
  • Bash
  • Output (JSON)

  curl -L -X GET \
     "https://api.cloud.nextmv.io/v1/account/queue" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $NEXTMV_API_KEY"
  

  Copy