Using execution classes¶

Info

Learn the concepts and fundamentals of execution classes in the Explanation page.

Execution classes define the characteristics of how instances are executed, such as:

cores
memory
maximum run time
GPU acceleration

You can customize the execution classes used by runs by modifying the instance configuration, or directly when starting a run.

Using execution classes when running¶

You can use allowed execution classes when starting a run, with the POST /v1/applications/{application_id}/runs endpoint, in two ways:

Use directly when starting a run by setting the execution_class field of the configuration object in the run's request payload, or
Attach it to an instance by setting the execution_class field of the configuration object when creating or updating an instance, and use that instance when starting a run.

Here is an example where the execution class is used directly when starting a run.

BashOutput

curl -s -X POST "https://api.cloud.nextmv.io/v1/applications/glowing-otter/runs?instance_id=latest" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {"name": "world", "radius": 6378, "distance": 147.6},
    "configuration": {"execution_class": "6c9500mb870s"}
  }' \
  | jq '.'

{
  "run_id": "latest-S9-E9QEDg"
}

Once the run finishes, retrieve its metadata using the run_id with the GET /v1/applications/{application_id}/runs/{run_id}/metadata endpoint. The result includes the applied execution_class, along with other metadata such as the status.

BashOutput

curl -s -X GET "https://api.cloud.nextmv.io/v1/applications/glowing-otter/runs/latest-S9-E9QEDg/metadata" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  | jq '.'

{
  "id": "latest-S9-E9QEDg",
  "user_email": "sebastian@nextmv.io",
  "name": "",
  "description": "",
  "metadata": {
    "status": "succeeded",
    "status_v2": "succeeded",
    "created_at": "2026-07-29T14:28:47Z",
    "initiated_at": "2026-07-29T14:28:47.868854706Z",
    "duration": 4399,
    "execution_duration": 4103,
    "input_size": 52,
    "output_size": 25099,
    "error": "",
    "application_id": "glowing-otter",
    "application_instance_id": "latest",
    "application_version_id": "",
    "execution_class": "6c9500mb870s",
    "runtime": "python-3_11",
    "run_type": {
      "type": "standard",
      "definition_id": "",
      "reference_id": ""
    },
    "format": {
      "input": {
        "type": "json"
      },
      "output": {
        "type": "json"
      }
    },
    "options": {
      "active_options": {
        "details": "true"
      },
      "request_options": null,
      "options_summary": [
        {
          "name": "details",
          "value": "true",
          "source": "version"
        }
      ]
    },
    "queuing_priority": 6,
    "queuing_disabled": false,
    "metrics": {
      "message": "Hello, world",
      "value": 1.23
    }
  }
}

Once the run completes, you can retrieve the results using the run_id with the GET /v1/applications/{application_id}/runs/{run_id} endpoint.

BashOutput

curl -s -X GET "https://api.cloud.nextmv.io/v1/applications/glowing-otter/runs/latest-S9-E9QEDg" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  | jq 'del(.output.assets)'

{
  "id": "latest-S9-E9QEDg",
  "user_email": "sebastian@nextmv.io",
  "name": "",
  "description": "",
  "metadata": {
    "status": "succeeded",
    "status_v2": "succeeded",
    "created_at": "2026-07-29T14:28:47Z",
    "initiated_at": "2026-07-29T14:28:47.868854706Z",
    "duration": 4399,
    "execution_duration": 4103,
    "input_size": 52,
    "output_size": 25099,
    "error": "",
    "application_id": "glowing-otter",
    "application_instance_id": "latest",
    "application_version_id": "",
    "execution_class": "6c9500mb870s",
    "runtime": "python-3_11",
    "run_type": {
      "type": "standard",
      "definition_id": "",
      "reference_id": ""
    },
    "format": {
      "input": {
        "type": "json"
      },
      "output": {
        "type": "json"
      }
    },
    "options": {
      "active_options": {
        "details": "true"
      },
      "request_options": null,
      "options_summary": [
        {
          "name": "details",
          "value": "true",
          "source": "version"
        }
      ]
    },
    "queuing_priority": 6,
    "queuing_disabled": false,
    "metrics": {
      "message": "Hello, world",
      "value": 1.23
    }
  },
  "output": {
    "options": {
      "details": true
    },
    "solution": {
      "message": "Hello, world"
    },
    "metrics": {
      "value": 1.23,
      "message": "Hello, world"
    }
  }
}

.output.assets was removed from the response above for a cleaner display.

Let's say we have an instance identified as production. First, let's update it to use a specific execution class with the PUT /v1/applications/{application_id}/instances/{instance_id} endpoint.

The endpoint expects the full instance payload, so get the instance 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 instance, uses jq to merge the configuration field into that response, and pipes the merged payload to a PUT request that updates the instance.

BashOutput

curl -s -X GET "https://api.cloud.nextmv.io/v1/applications/glowing-otter/instances/production" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  | jq '. + {"configuration": {"execution_class": "6c9500mb870s"}}' \
  | curl -s -X PUT "https://api.cloud.nextmv.io/v1/applications/glowing-otter/instances/production" \
      -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
      -H "Content-Type: application/json" \
      -d @- \
  | jq '.'

{
  "name": "The main production instance",
  "id": "production",
  "application_id": "glowing-otter",
  "version_id": "v0.0.1",
  "description": "",
  "configuration": {
    "execution_class": "6c9500mb870s",
    "queuing": {
      "priority": 6,
      "disabled": false
    }
  },
  "locked": false,
  "created_at": "2026-07-29T14:30:09.498980495Z",
  "updated_at": "2026-07-29T14:30:21.041733313Z"
}

We can now start a run using the production instance, and the attached execution class will be used automatically.

BashOutput

curl -s -X POST "https://api.cloud.nextmv.io/v1/applications/glowing-otter/runs?instance_id=production" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"input": {"name": "world", "radius": 6378, "distance": 147.6}}' \
  | jq '.'

{
  "run_id": "production-TWEwrQEDg"
}

Once the run completes, retrieve the results using the same GET /v1/applications/{application_id}/runs/{run_id} endpoint used above.

BashOutput

curl -s -X GET "https://api.cloud.nextmv.io/v1/applications/glowing-otter/runs/production-TWEwrQEDg" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  | jq 'del(.output.assets)'

{
  "id": "production-TWEwrQEDg",
  "user_email": "sebastian@nextmv.io",
  "name": "",
  "description": "",
  "metadata": {
    "status": "succeeded",
    "status_v2": "succeeded",
    "created_at": "2026-07-29T14:30:28Z",
    "initiated_at": "2026-07-29T14:30:28.408992094Z",
    "duration": 4860,
    "execution_duration": 4605,
    "input_size": 52,
    "output_size": 25099,
    "error": "",
    "application_id": "glowing-otter",
    "application_instance_id": "production",
    "application_version_id": "v0.0.1",
    "execution_class": "6c9500mb870s",
    "runtime": "python-3_11",
    "run_type": {
      "type": "standard",
      "definition_id": "",
      "reference_id": ""
    },
    "format": {
      "input": {
        "type": "json"
      },
      "output": {
        "type": "json"
      }
    },
    "options": {
      "active_options": {
        "details": "true"
      },
      "request_options": null,
      "options_summary": [
        {
          "name": "details",
          "value": "true",
          "source": "version"
        }
      ]
    },
    "queuing_priority": 6,
    "queuing_disabled": false,
    "metrics": {
      "message": "Hello, world",
      "value": 1.23
    }
  },
  "output": {
    "options": {
      "details": true
    },
    "solution": {
      "message": "Hello, world"
    },
    "metrics": {
      "value": 1.23,
      "message": "Hello, world"
    }
  }
}