Using managed inputs¶

Info

Learn the concepts and fundamentals of managed inputs in the Explanation page.

Managed inputs are used to store and keep track of your inputs. They can be created either by referencing a prior run within your application, or by uploading new data. You can use managed inputs for runs as well as other features of the Nextmv Platform:

Scenario tests: when creating a scenario test with the Application.new_scenario_test method, you can define scenarios using managed inputs as the data source.
Input sets: use them to create batch experiments or scenario tests. When using the Application.new_input_set method, you can define one or more managed inputs to make up the input set.

Included in this how-to guide are instructions on how to interact with managed inputs using methods on the Application class. Go the reference section to see all the available parameters for each method.

Create a managed input¶

Use the Application.new_managed_input method to create a new managed input for an application. Managed inputs can be created by one of the following methods:

From a run, by providing the run_id keyword argument.
From a file (or directory) that is uploaded to Nextmv Cloud, by providing the upload_id keyword argument.

To know which type of content format is expected for the managed input, we recommend you specify the format keyword argument, passing it a Format object. Use FormatInput to set the format_input attribute, specifying a ContentFormat value such as ContentFormat.JSON.

Here is an example that creates a json managed input from an existing run ID.

main.pyBashOutput

import os

import nextmv
from nextmv import cloud
from nextmv import ContentFormat, Format, FormatInput

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="uncanny-rodent")
managed_input = app.new_managed_input(
    run_id="latest-7GpajyPvg",
    format=Format(format_input=FormatInput(input_type=ContentFormat.JSON)),
)

nextmv.write(managed_input.to_dict())

uv run main.py

{
  "id": "managed-input-65urvabz",
  "name": "managed-input-65urvabz",
  "description": "",
  "run_id": "latest-7GpajyPvg",
  "upload_id": "",
  "format": {
    "input": {
      "type": "json"
    }
  },
  "created_at": "2026-07-28T20:06:13.263328Z",
  "updated_at": "2026-07-28T20:06:13.263328Z"
}

If you have data in the filesystem that you want to upload as a managed input, there are a couple more steps to complete.

Create a new upload using the Application.upload_url method.
```
url = app.upload_url()
```
The returned object contains an upload_id and an upload_url. Let's use the upload_url with the Application.upload_data method to upload the actual data to Nextmv Cloud. This can be a file (json) or a directory (multi-file).
```
with open("input.json") as f:
    input_data = json.load(f)

app.upload_data(data=input_data, upload_url=url)
```

Once the data has been uploaded, we can create a managed input from it, by using the upload_id that was returned when the upload was created.

main.pyBashOutput

import json
import os

import nextmv
from nextmv import cloud
from nextmv import ContentFormat, Format, FormatInput

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="uncanny-rodent")

url = app.upload_url()

with open("input.json") as f:
    input_data = json.load(f)

app.upload_data(data=input_data, upload_url=url)

managed_input = app.new_managed_input(
    upload_id=url.upload_id,
    format=Format(format_input=FormatInput(input_type=ContentFormat.JSON)),
)

nextmv.write(managed_input.to_dict())

uv run main.py

{
  "id": "managed-input-ikbrsgbl",
  "name": "managed-input-ikbrsgbl",
  "description": "",
  "run_id": "",
  "upload_id": "a107c7d2-b4ab-4e97-bdcb-799be2e67359",
  "format": {
    "input": {
      "type": "json"
    }
  },
  "created_at": "2026-07-28T20:06:28.859500Z",
  "updated_at": "2026-07-28T20:06:28.859500Z"
}

For multi-file, just set the format_input.input_type attribute to ContentFormat.MULTI_FILE. When uploading data, package your directory into a tar file and pass it to Application.upload_data using the tar_file keyword argument.

The call above will create a random ID, and use the same identifier for the managed input's name. The name of the managed input is used as a human-readable label. You can use the id and/or name keyword arguments to specify a custom ID and name for the managed input. For example:

main.pyBashOutput

import json
import os

import nextmv
from nextmv import cloud
from nextmv import ContentFormat, Format, FormatInput

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="uncanny-rodent")

url = app.upload_url()

with open("input.json") as f:
    input_data = json.load(f)

app.upload_data(data=input_data, upload_url=url)

managed_input = app.new_managed_input(
    upload_id=url.upload_id,
    format=Format(format_input=FormatInput(input_type=ContentFormat.JSON)),
    id="baxter-burrow",
    name="The managed input of Baxter's Burrow",
)

nextmv.write(managed_input.to_dict())

uv run main.py

{
  "id": "baxter-burrow",
  "name": "The managed input of Baxter's Burrow",
  "description": "",
  "run_id": "",
  "upload_id": "7a3ba4a9-a1ba-4a09-82fa-8942deae2d22",
  "format": {
    "input": {
      "type": "json"
    }
  },
  "created_at": "2026-07-24T19:15:38.853798Z",
  "updated_at": "2026-07-24T19:15:38.853798Z"
}

Run with a managed input¶

Once a managed input has been created you can use it with the Application.new_run_with_result method (or Application.new_run) by means of the managed_input_id keyword argument. For example:

main.pyBashOutput

import os

import nextmv
from nextmv import cloud

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="uncanny-rodent")
run_result = app.new_run_with_result(
    managed_input_id="baxter-burrow",
    instance_id="latest",
)

result = run_result.to_dict()
result["output"].pop("assets", None)  # Assets are omitted here for a cleaner display.

nextmv.write(result)

uv run main.py

{
  "description": "",
  "id": "latest-1T4ECyEDR",
  "metadata": {
    "application_id": "uncanny-rodent",
    "application_instance_id": "latest",
    "application_version_id": "",
    "created_at": "2026-07-28T20:07:33Z",
    "duration": 4345.0,
    "error": "",
    "execution_class": "6c9500mb870s",
    "execution_duration": 3883.0,
    "format": {
      "input": {
        "type": "json"
      },
      "output": {
        "type": "json"
      }
    },
    "initiated_at": "2026-07-28T20:07:34.099786Z",
    "input_size": 63.0,
    "metrics": {
      "message": "Hello, Patches",
      "value": 1.23
    },
    "options": {
      "active_options": {
        "details": "true"
      },
      "options_summary": [
        {
          "name": "details",
          "source": "version",
          "value": "true"
        }
      ]
    },
    "output_size": 917.0,
    "queuing_disabled": false,
    "queuing_priority": 6,
    "run_type": {
      "type": "standard",
      "definition_id": "",
      "reference_id": ""
    },
    "runtime": "python-3_11",
    "status_v2": "succeeded",
    "tracking": {
      "input_id": "baxter-burrow"
    }
  },
  "name": "",
  "user_email": "sebastian@nextmv.io",
  "console_url": "https://cloud.nextmv.io/app/uncanny-rodent/run/latest-1T4ECyEDR?view=details",
  "output": {
    "options": {
      "details": true
    },
    "solution": {
      "message": "Hello, Patches"
    },
    "metrics": {
      "value": 1.23,
      "message": "Hello, Patches"
    }
  }
}

Get a managed input¶

Use the Application.managed_input method to retrieve an existing managed input for an application by its ID. The method returns a ManagedInput object.

main.pyBashOutput

import os

import nextmv
from nextmv import cloud

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="uncanny-rodent")
managed_input = app.managed_input(managed_input_id="baxter-burrow")

nextmv.write(managed_input.to_dict())

uv run main.py

{
  "id": "baxter-burrow",
  "name": "The managed input of Baxter's Burrow",
  "description": "",
  "run_id": "",
  "upload_id": "7a3ba4a9-a1ba-4a09-82fa-8942deae2d22",
  "format": {
    "input": {
      "type": "json"
    }
  },
  "created_at": "2026-07-24T19:15:38.853798Z",
  "updated_at": "2026-07-24T19:15:38.853798Z"
}

You can list all managed inputs in the application using the Application.list_managed_inputs method.

main.pyBashOutput

import json
import os

from nextmv import cloud

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="uncanny-rodent")
managed_inputs = app.list_managed_inputs()

print(json.dumps([managed_input.to_dict() for managed_input in managed_inputs[:3]], indent=2))

uv run main.py

[
  {
    "id": "managed-input-ikbrsgbl",
    "name": "managed-input-ikbrsgbl",
    "description": "",
    "run_id": "",
    "upload_id": "a107c7d2-b4ab-4e97-bdcb-799be2e67359",
    "format": {
      "input": {
        "type": "json"
      }
    },
    "created_at": "2026-07-28T20:06:28.859500Z",
    "updated_at": "2026-07-28T20:06:28.859500Z"
  },
  {
    "id": "managed-input-65urvabz",
    "name": "managed-input-65urvabz",
    "description": "",
    "run_id": "latest-7GpajyPvg",
    "upload_id": "",
    "format": {
      "input": {
        "type": "json"
      }
    },
    "created_at": "2026-07-28T20:06:13.263328Z",
    "updated_at": "2026-07-28T20:06:13.263328Z"
  },
  {
    "id": "input.json-8MFSJpPDg",
    "name": "input.json",
    "description": "",
    "run_id": "",
    "upload_id": "9008eb61-dd50-4d8a-af83-3d508a766aa8",
    "format": {
      "input": {
        "type": "json"
      }
    },
    "created_at": "2026-07-24T19:17:19.848940Z",
    "updated_at": "2026-07-24T19:17:19.848940Z"
  }
]

Update a managed input¶

You can update attributes of a managed input with the Application.update_managed_input method, such as its:

Name
Description

Go the reference section to see all the available parameters for updating a managed input. You cannot update the ID or actual input data. If you need to change the data, you must create a new managed input.

main.pyBashOutput

import os

import nextmv
from nextmv import cloud

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="uncanny-rodent")
managed_input = app.update_managed_input(
    managed_input_id="baxter-burrow",
    name="This is an updated burrow for the Baxter managed input",
    description="A brand new description for the Baxter managed input",
)

nextmv.write(managed_input.to_dict())

uv run main.py

{
  "id": "baxter-burrow",
  "name": "This is an updated burrow for the Baxter managed input",
  "description": "A brand new description for the Baxter managed input",
  "run_id": "",
  "upload_id": "7a3ba4a9-a1ba-4a09-82fa-8942deae2d22",
  "format": {
    "input": {
      "type": "json"
    }
  },
  "created_at": "2026-07-24T19:15:38.853798Z",
  "updated_at": "2026-07-28T20:08:50.757297Z"
}

Delete a managed input¶

Warning

Deleting a managed input is irreversible. All the information associated with the managed input will be permanently deleted.

Delete a managed input using the Application.delete_managed_input method.

main.pyBash

import os

from nextmv import cloud

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="uncanny-rodent")
app.delete_managed_input(managed_input_id="baxter-burrow")

uv run main.py