Run App Remotely

Large payloads on remote runs

A tutorial for handling large payloads when running remotely.

If you use the Nextmv CLI or Python SDK, you do not need to worry about large payloads. They handle the complete run workflow for you.

When submitting a new run and retrieving the run's results, there are size limits to consider for the payload: 5MB for the input and output of a run.

You can use this large payloads workflow to handle bigger sizes. When using this alternative, note that:

  • There is a maximum limit of 500MB when uploading a file.
  • There is a maximum limit of 100MB when downloading a file.

To achieve this, you can use one of these interfaces:

  • Cloud API
  • Python SDK

To work with large payloads, follow these steps:

large-file

1. Request a presigned URL

Request a presigned URL to upload your large input file to.

POSThttps://api.cloud.nextmv.io/v1/applications/{application_id}/runs/uploadurl

Retrieve unique upload URL and ID.

Retrieve a unique URL and ID for uploading run input (for large input files).

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

The result will contain an upload_id and upload_url.

{
  "upload_id": "ae7dce...",
  "upload_url": "https://production-nextmv-tmp..."
}
Copy

This returned upload URL will only last for 15 minutes. If it expires, simply request a new one and take note of the new upload ID.

You can export the upload_id and upload_url to variables:

export UPLOAD_ID="ae7dce..."
export UPLOAD_URL="https://production-nextmv-tmp..."
Copy

2. Upload the large input

Upload your input using the upload_url that was obtained before.

curl -L -X PUT \
  $(echo -n $UPLOAD_URL) \
  -H "Content-Type: application/json" \
  --compressed \
  -d @$INPUT_FILE
Copy

An empty response means the upload was successful. Note that this may take a moment depending on the size of the input file.

3. Start the run

Once the upload has completed, you can start a new run with the large input using the upload_id from a previous step. This upload_id is sent in the body of the run request in place of the input. The result contains the run_id to retrieve the run results.

POSThttps://api.cloud.nextmv.io/v1/applications/{application_id}/runs

New application run.

Create new application run.

curl -L -X POST \
  "https://api.cloud.nextmv.io/v1/applications/$APP_ID/runs?instance_id=$INSTANCE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEXTMV_API_KEY" \
  -d "{
    \"upload_id\": \"$UPLOAD_ID\", 
    \"options\": {
      \"solve.duration\": \"10s\",
      \"solve.iterations\": \"20\"
    }
  }"
Copy

You should receive a run_id like normal as a response.

{
  "run_id": "latest-PLs7xtKSg"
}
Copy

4. Get the run result

To get the result of your run, you use the same endpoint as with a standard run but with the appended query parameter ?format=url. This will return a standard run result payload but instead of the run output included in the returned JSON, in its place will be a URL to download the output file.

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

Get run result.

Get the result of a run.

Note that the ?format=url query parameter can be used regardless of your output size.

curl -L -X GET \
  "https://api.cloud.nextmv.io/v1/applications/$APP_ID/runs/$RUN_ID?format=url" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEXTMV_API_KEY"
Copy

The output.url key contains the presigned URL to download the output.

{
  "id": "latest-PLs7xtKSg",
  "user_email": "sebastian@nextmv.io",
  "name": "",
  "description": "",
  "metadata": {
    "status": "succeeded",
    "created_at": "2024-01-04T17:56:38Z",
    "duration": 12379,
    "input_size": 3154,
    "output_size": 13814,
    "error": "",
    "application_id": "routing",
    "application_instance_id": "latest",
    "application_version_id": "v1.0.4"
  },
  "output": {
    "url": "https://production-nextmv-tmp-ru..."
  }
}
Copy

Finally, you can download the output using the presigned URL:

curl -L -X GET \
  $(echo -n $OUTPUT_URL) \
  -H "Content-Type: application/json"
Copy

Page last updated

Go to on-page nav menu