Input/output multi-file format

There are two main content formats supported by Nextmv when performing a new remote run of an application:

• json: the application reads from stdin, writes results to stdout, and logs to stderr. Input and output are expected to be in JSON format. This is the default content format.
• multi-file: the application reads input data from one, or more files, and writes output data to one, or more files. Logs are streamed to both stdout and stderr.

This documentation details how to work with the multi-file content format and the Cloud API. These are the steps that you must follow to start and get the results of a multi-file run.

1. Understand the multi-file convention.
2. Create the input archive.
3. Upload the input files.
4. Start a new run with the multi-file content format.
5. Wait for the run to finish / poll for status.
6. Download the output files.

1. The multi-file convention

If you want your application to work with the multi-file content format, it must follow these conventions:

• Input data must be read from one, or more, input files.
• Output data must be written to one, or more, output files.
• Output metrics (statistics) must be written to a .json file.
• Custom assets and visuals must be written to a .json file.
• Configurations (options) must be read from command-line arguments.

The app.yaml (app manifest) holds the configuration for the multi-file content format. Here is an example configuration:

configuration:
  content:
    format: multi-file
    multi-file:
      input:
        path: inputs
      output:
        solutions: outputs/solutions
        statistics: outputs/statistics/statistics.json
        assets: outputs/assets/assets.json

The example above is the default configuration for the multi-file content format. This means that if your application follows the default file structure and naming conventions, you do not need to specify any additional configuration in the app manifest.

• input/path is the directory (folder) where the input files are expected to be found. The input files should be either UTF8 encoded files (e.g. .csv, .json) or Microsoft Excel (.xlsx) documents. This folder is expected to be present when the application starts running. Your application can read input files from a different location, and in that case you must specify the correct path in the app manifest.

• outputs/solutions is a directory expected to contain the output of the run after the application completes processing. This output is expected to be one or more files that are either UTF8 encoded or Microsoft Excel (.xlsx) documents. This folder is then compressed into a gzip compressed tarball (.tar.gz) and stored on Nextmv Cloud as the output of the run. Your application can write solution files to a different location, and in that case you must specify the correct path in the app manifest.

• outputs/statistics is a directory expected to either be empty or contain statistics information for the run used for experimentation on the Nextmv Cloud platform. If empty, no statistics information is recorded on the run on the Nextmv Cloud. To output statistics to the Nextmv Cloud from the run, the application should create a statistics.json file within outputs/statistics that contains a JSON object following the Nextmv statistics convention. Your application can write the statistics file to a different location, and in that case you must specify the correct path in the app manifest.

• outputs/assets is a directory expected to either be empty or contain additional assets for the run that can contain supplemental or transformative files that are generally not informationally additive to the output, such as, but not limited to, assets for enabling custom visualization of run results on Nextmv Console. If empty, no assets are recorded on the run on the Nextmv Cloud. To output assets to the Nextmv Cloud from the run, the application should create a assets.json file within outputs/assets that contains a JSON object following the Nextmv run assets convention. Your application can write the assets file to a different location, and in that case you must specify the correct path in the app manifest.

This section showed how to configure the app.yaml manifest to use the multi-file content format. In addition to configuring it in the manifest, there are two other ways in which you can specify the multi-file content format so that a run can use it.

1. Specify the multi-file content format in the run creation request payload. This will be addressed in step 4 of this guide.
2. Specify the multi-file content format in the instance configuration.

The hierarchy of precedence for the content format configuration is as follows:

1. Run creation request payload. This takes highest precedence.
2. Instance configuration.
3. App manifest configuration.

2. Create the input archive

Input files should be all placed within a single directory (folder). The input folder must be compressed into a tar archive compressed with gzip (.tar.gz). This archive must contain only either UTF8 encoded files or Microsoft Excel (.xlsx) documents.

Consider the following example. We will create a directory inputs/ and two files within that directory:

• file_1.csv
• file_2.json

order_id,customer_id,order_due,order_value
1,1,2021-01-01,100
2,2,2021-01-02,200
3,3,2021-01-03,300
4,4,2021-01-04,400

The structure of the current working directory should look like this:

.
└── inputs
    ├── file_1.csv
    └── file_2.json

Then, we will compress the inputs directory into an archive using tar.

tar -czvf inputs.tar.gz inputs

A file named inputs.tar.gz should have been created in the current working directory. Once the archive is created, the structure of the current working directory should look like this:

.
├── inputs
│   ├── file_1.csv
│   └── file_2.json
└── inputs.tar.gz

3. Upload the input files

You are now going to upload the inputs.tar.gz file to Nextmv Cloud to prepare it for use on a run.

Request a presigned URL to upload your input archive to.

curl -sS -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" | jq

Note that you must specify the correct APP_ID path parameter. The result will contain an upload_id and upload_url.

{
  "upload_id": "00000000-0000-0000-0000-000000000000",
  "upload_url": "https://the-upload-url.com/some-hashes"
}

You will need the upload_id to start a run and the upload_url to actually upload the input archive.

Upload your input using the upload_url that was obtained before. We use --data-binary here to make sure curl sends the content of the file unaltered.

curl -sS -L -X PUT \
  <UPLOAD_URL_OBTAINED_FROM_PREVIOUS_STEP> \
  -H "Content-Type: application/json" \
  --compressed \
  --data-binary @inputs.tar.gz

In the above code snippet, replace <UPLOAD_URL_OBTAINED_FROM_PREVIOUS_STEP> with the actual upload_url obtained from the previous step. Also note that if you named the .tar.gz file differently, you should replace inputs.tar.gz with the actual name of your file.

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

4. Start a new run with the multi-file content format

Use the following endpoint to start a new run.

When creating a run that uses multi-file content format input, you must ensure these requirements are met:

1. The run creation payload must include the upload_id obtained from the input upload step.
2. If not specified in the app.yaml or instance configuration, the run's configuration must specify that the input content format is multi-file.

{
  "upload_id": "ae7dce...",
  "configuration": {
    "format": {
      "input": {
        "type": "multi-file"
      }
    }
  }
}

Here is a sample curl command that showcases the use of the upload_id and the multi-file content format in the run creation request.

curl -sS -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":"ae7dce...","configuration":{"format":{"input":{"type":"multi-file"}}}}' | jq

Note that you must specify the correct APP_ID and INSTANCE_ID path parameters.

After the run is created, take note of the run_id from the response. You will need it to poll for status and download the output files.

5. Poll for status / wait for the run to finish

As it is described in the run methodology, you must poll for the status of the run until it is completed. The run metadata can be retrieved while the run is still in progress (or at any point). The metadata.status_v2 key will contain the status of the run.

Sample curl request for obtaining metadata for a run:

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

Once the run has finished, you can proceed to download the output files.

6. Download the output files

In the same way as with inputs, the output consists of one or more files. Use the following endpoint to retrieve the results of the run. You must specify the format=url query parameter to indicate that you want to receive a URL to download the output files, otherwise you get a 400 error.

Here is a sample curl command that showcases how to get the output URL for a completed run.

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

Note that you must specify the correct APP_ID and RUN_ID path parameters.

With this command, you should receive a response similar to this one:

{
  "id": "latest-HqcLisGDR",
  "user_email": "...",
  "name": "",
  "description": "",
  "metadata": {
    "status": "succeeded",
    "status_v2": "succeeded",
    "created_at": "2025-12-16T19:32:43Z",
    "duration": 38536,
    "execution_duration": 37327,
    "input_size": 2653,
    "output_size": 2653,
    "error": "",
    "application_id": "...",
    "application_instance_id": "latest",
    "application_version_id": "",
    "execution_class": "6c9500mb870s",
    "runtime": "...",
    "run_type": {
      "type": "standard",
      "definition_id": "",
      "reference_id": ""
    },
    "format": {
      "input": {
        "type": "multi-file"
      },
      "output": {
        "type": "multi-file"
      }
    },
    "options": {...},
    "queuing_priority": 6,
    "queuing_disabled": false,
    "statistics": {...}
  },
  "output": {
    "url": "https://..."
  }
}

For a json content format run, the output key would contain the actual output data. However, since this is a multi-file content format run, the output key contains a url key with a presigned URL to download the output archive.

You can download the output archive using curl as follows:

curl -L -X GET \
  <OUTPUT_URL_HERE> \
  -o output.tar.gz

Replace <OUTPUT_URL_HERE> with the actual URL from the output.url field in the previous response.

An output.tar.gz file should have been created in the current working directory. You can also name it something else if you prefer. You can extract the contents of this archive using tar as follows:

mkdir outputs && tar -xzvf output.tar.gz -C outputs

This command will create an outputs/ directory and extract the contents of the archive into that directory.

The structure of the current working directory should look like this:

.
├── inputs
│   ├── file_1.csv
│   └── file_2.json
├── inputs.tar.gz
├── output.tar.gz
└── outputs
    ├── output_1.csv
    └── output_2.csv

The outputs/ directory now contains the output files generated by the run. This example shows two sample output files but your actual output files may vary depending on your application logic.