Skip to content

Using input sets

Info

Learn the concepts and fundamentals of input sets in the Explanation page.

Input sets are defined sets of input files to use for tests and experiments, such as:

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

Create an input set

Use the Application.new_input_set method to create a new input set for an application. You can create an input set from the following data sources:

  • run_ids: Create from a list of existing run IDs.
  • inputs: Create from existing managed inputs in the application, using a list of ManagedInput objects.
  • instance_id with start_time and end_time: Create from instance runs matching the time range criteria. You may additionally use the maximum_runs keyword argument to limit the number of runs used.

Here is an example that creates an input set using run IDs.

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")
input_set = app.new_input_set(
    run_ids=["production-TkvxQ8EDR", "production-P3DxQ8EDg", "production-CUdxQ8Pvg"],
)

nextmv.write(input_set.to_dict())

uv run main.py

{
  "app_id": "uncanny-rodent",
  "created_at": "2026-07-29T04:14:51.770237Z",
  "description": "",
  "id": "input-set-5tkpdobo",
  "input_ids": [
    "production-TkvxQ8EDR",
    "production-P3DxQ8EDg",
    "production-CUdxQ8Pvg"
  ],
  "name": "input-set-5tkpdobo",
  "updated_at": "2026-07-29T04:14:51.770237Z",
  "inputs": []
}

Here is an example that creates an input set using managed inputs.

import os

import nextmv
from nextmv import cloud
from nextmv.cloud import ManagedInput

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="uncanny-rodent")
input_set = app.new_input_set(
    inputs=[ManagedInput(id="baxter-burrow")],
)

nextmv.write(input_set.to_dict())

uv run main.py

{
  "app_id": "uncanny-rodent",
  "created_at": "2026-07-29T04:14:56.340413Z",
  "description": "",
  "id": "input-set-ak30ktv9",
  "input_ids": [],
  "name": "input-set-ak30ktv9",
  "updated_at": "2026-07-29T04:14:56.340413Z",
  "inputs": [
    {
      "id": "baxter-burrow",
      "name": "The managed input of Baxter's Burrow",
      "description": ""
    }
  ]
}

The calls above will create a random ID, and use the same identifier for the input set's name. The name of the input set 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 input set. For example:

import os

import nextmv
from nextmv import cloud
from nextmv.cloud import ManagedInput

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="uncanny-rodent")
input_set = app.new_input_set(
    inputs=[ManagedInput(id="baxter-burrow")],
    id="impressive-rabbit",
    name="Input set for an impressive rabbit",
)

nextmv.write(input_set.to_dict())

uv run main.py

{
  "app_id": "uncanny-rodent",
  "created_at": "2026-07-29T04:15:00.940269Z",
  "description": "",
  "id": "impressive-rabbit",
  "input_ids": [],
  "name": "Input set for an impressive rabbit",
  "updated_at": "2026-07-29T04:15:00.940269Z",
  "inputs": [
    {
      "id": "baxter-burrow",
      "name": "The managed input of Baxter's Burrow",
      "description": ""
    }
  ]
}

Get an input set

You can get an input set using the Application.input_set method. The method returns an InputSet object.

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")
input_set = app.input_set(input_set_id="impressive-rabbit")

nextmv.write(input_set.to_dict())

uv run main.py

{
  "app_id": "uncanny-rodent",
  "created_at": "2026-07-29T04:15:00.940269Z",
  "description": "",
  "id": "impressive-rabbit",
  "input_ids": [],
  "name": "Input set for an impressive rabbit",
  "updated_at": "2026-07-29T04:15:00.940269Z",
  "inputs": [
    {
      "id": "baxter-burrow",
      "name": "The managed input of Baxter's Burrow",
      "description": ""
    }
  ]
}

You can list all input sets in the application using the Application.list_input_sets method.

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")
input_sets = app.list_input_sets()

print(json.dumps([input_set.to_dict() for input_set in input_sets[:2]], indent=2))

uv run main.py

[
  {
    "app_id": "uncanny-rodent",
    "created_at": "2026-07-29T04:15:00.940269Z",
    "description": "",
    "id": "impressive-rabbit",
    "input_ids": [],
    "name": "Input set for an impressive rabbit",
    "updated_at": "2026-07-29T04:15:00.940269Z",
    "inputs": [
      {
        "id": "baxter-burrow",
        "name": "The managed input of Baxter's Burrow",
        "description": ""
      }
    ]
  },
  {
    "app_id": "uncanny-rodent",
    "created_at": "2026-07-29T04:14:56.340413Z",
    "description": "",
    "id": "input-set-ak30ktv9",
    "input_ids": [],
    "name": "input-set-ak30ktv9",
    "updated_at": "2026-07-29T04:14:56.340413Z",
    "inputs": [
      {
        "id": "baxter-burrow",
        "name": "The managed input of Baxter's Burrow",
        "description": ""
      }
    ]
  }
]

Update an input set

You can update attributes of an input set with the Application.update_input_set method, such as its:

  • Name
  • Description
  • Managed inputs

You cannot update the ID of an input set. It is possible to update the managed inputs of an input set through the inputs keyword argument. If an input set was created with runs, and it has input_ids defined on it, you cannot update these at this moment. If you do attempt to update an input set, by passing managed inputs, and it has input_ids defined, the latter will be removed from the input set.

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")
input_set = app.update_input_set(
    id="impressive-rabbit",
    name="Updated Input Set Name",
    description="Updated description for the input set",
)

nextmv.write(input_set.to_dict())

uv run main.py

{
  "app_id": "uncanny-rodent",
  "created_at": "2026-07-29T04:15:00.940269Z",
  "description": "Updated description for the input set",
  "id": "impressive-rabbit",
  "input_ids": [],
  "name": "Updated Input Set Name",
  "updated_at": "2026-07-29T04:15:14.485368Z",
  "inputs": [
    {
      "id": "baxter-burrow",
      "name": "The managed input of Baxter's Burrow",
      "description": ""
    }
  ]
}

Delete an input set

Warning

Deleting an input set is irreversible. All the data associated with the input set will be permanently deleted.

Delete an input set using the Application.delete_input_set method.

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_input_set(input_set_id="impressive-rabbit")

uv run main.py