Methodology

Run methodology

Running an app remotely with 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. 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:

The Nextmv CLI and Python SDK handle the complete run workflow: large payloads, polling, retries, status checking, timeouts, exponential backoff, and more for you.

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.

There is a size limit of 5MB when directly submitting/retrieving the input/output with the API endpoints. Larger payloads must use the large file method.

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.

    nextmv app cancel \
       --app-id "<YOUR-APP-ID>" \
       --run-id "<YOUR-RUN-ID>"
    
    Copy
  • Python SDK. Use the Application.cancel_run method.

    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.

    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.

    nextmv account queue
    
    Copy
  • Python SDK. Use the Account.queue method.

    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.

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

Page last updated

Go to on-page nav menu