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:

This how-to guide explains how to interact with input sets using the /v1/applications/{application_id}/experiments/inputsets endpoints. Go to the reference section to see all the available parameters for each endpoint.

Create an input set¶

Use the POST /v1/applications/{application_id}/experiments/inputsets endpoint to create a new input set for an application. The endpoint requires a name in the request payload. 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 InputSetInput 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 field to limit the number of runs used.

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

BashOutput

ID="input-set-$(openssl rand -hex 4)"

curl -s -X POST "https://api.cloud.nextmv.io/v1/applications/uncanny-rodent/experiments/inputsets" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{\"id\": \"${ID}\", \"name\": \"${ID}\", \"run_ids\": [\"production-TkvxQ8EDR\", \"production-P3DxQ8EDg\", \"production-CUdxQ8Pvg\"]}" \
  | jq '.'

{
  "id": "input-set-f5499e22",
  "name": "input-set-f5499e22",
  "description": "",
  "app_id": "uncanny-rodent",
  "created_at": "2026-07-29T14:30:09.391599514Z",
  "input_ids": [
    "production-TkvxQ8EDR",
    "production-P3DxQ8EDg",
    "production-CUdxQ8Pvg"
  ],
  "updated_at": "2026-07-29T14:30:09.391599514Z",
  "inputs": []
}

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

BashOutput

ID="input-set-$(openssl rand -hex 4)"

curl -s -X POST "https://api.cloud.nextmv.io/v1/applications/uncanny-rodent/experiments/inputsets" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{\"id\": \"${ID}\", \"name\": \"${ID}\", \"inputs\": [{\"id\": \"baxter-burrow\"}]}" \
  | jq '.'

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

The calls above use a randomly generated ID, and the same identifier for the input set's name. The name of the input set is used as a human-readable label. You can pass different values for the id and name fields in the payload to specify a custom ID and name for the input set. For example:

BashOutput

curl -s -X POST "https://api.cloud.nextmv.io/v1/applications/uncanny-rodent/experiments/inputsets" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"id": "impressive-rabbit", "name": "Input set for an impressive rabbit", "inputs": [{"id": "baxter-burrow"}]}' \
  | jq '.'

{
  "id": "impressive-rabbit",
  "name": "Input set for an impressive rabbit",
  "description": "",
  "app_id": "uncanny-rodent",
  "created_at": "2026-07-29T14:30:18.777587992Z",
  "input_ids": [],
  "updated_at": "2026-07-29T14:30:18.777587992Z",
  "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 GET /v1/applications/{application_id}/experiments/inputsets/{input_set_id} endpoint. The endpoint returns an InputSet object.

BashOutput

curl -s -X GET "https://api.cloud.nextmv.io/v1/applications/uncanny-rodent/experiments/inputsets/impressive-rabbit" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  | jq '.'

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

You can list all input sets in the application using the GET /v1/applications/{application_id}/experiments/inputsets endpoint. This endpoint is paginated, so the snippet below always uses pagination: it passes pagereturn=true to receive a next_page_token in the response, and keeps requesting pages by passing that token back as pagetoken until no token is returned.

BashOutput

ITEMS="[]"
PAGE_TOKEN=""

while :; do
  RESPONSE=$(curl -s -G "https://api.cloud.nextmv.io/v1/applications/uncanny-rodent/experiments/inputsets" \
    -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
    --data-urlencode "pagereturn=true" \
    --data-urlencode "pagetoken=${PAGE_TOKEN}")

  ITEMS=$(jq -n --argjson existing "$ITEMS" --argjson page "$(echo "$RESPONSE" | jq '.items')" '$existing + $page')
  PAGE_TOKEN=$(echo "$RESPONSE" | jq -r '.next_page_token // empty')

  [ -z "$PAGE_TOKEN" ] && break
done

echo "$ITEMS" | jq '.[:2]'

[
  {
    "id": "impressive-rabbit",
    "name": "Input set for an impressive rabbit",
    "description": "",
    "app_id": "uncanny-rodent",
    "created_at": "2026-07-29T14:30:18.777587992Z",
    "input_ids": [],
    "updated_at": "2026-07-29T14:30:18.777587992Z",
    "inputs": [
      {
        "id": "baxter-burrow",
        "name": "The managed input of Baxter's Burrow",
        "description": ""
      }
    ]
  },
  {
    "id": "input-set-d4911174",
    "name": "input-set-d4911174",
    "description": "",
    "app_id": "uncanny-rodent",
    "created_at": "2026-07-29T14:30:13.226034795Z",
    "input_ids": [],
    "updated_at": "2026-07-29T14:30:13.226034795Z",
    "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 PUT /v1/applications/{application_id}/experiments/inputsets/{input_set_id} endpoint, 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 field in the payload. 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.

The endpoint expects the full input set payload, so get the input set first and merge in the fields you want to change.

The snippet below does this in three steps: it sends a GET request to fetch the current input set, uses jq to merge the name and description fields into that response, and pipes the merged payload to a PUT request that updates the input set.

BashOutput

curl -s -X GET "https://api.cloud.nextmv.io/v1/applications/uncanny-rodent/experiments/inputsets/impressive-rabbit" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  | jq '. + {"name": "Updated Input Set Name", "description": "Updated description for the input set"}' \
  | curl -s -X PUT "https://api.cloud.nextmv.io/v1/applications/uncanny-rodent/experiments/inputsets/impressive-rabbit" \
      -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
      -H "Content-Type: application/json" \
      -d @- \
  | jq '.'

{
  "id": "impressive-rabbit",
  "name": "Updated Input Set Name",
  "description": "Updated description for the input set",
  "app_id": "uncanny-rodent",
  "created_at": "2026-07-29T14:30:18.777587992Z",
  "input_ids": [],
  "updated_at": "2026-07-29T14:30:31.791163042Z",
  "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 DELETE /v1/applications/{application_id}/experiments/inputsets/{input_set_id} endpoint.

Bash

curl -s -X DELETE "https://api.cloud.nextmv.io/v1/applications/uncanny-rodent/experiments/inputsets/impressive-rabbit" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}"