Skip to content

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 with the Application.new_run_with_result method (or Application.new_run) in two ways:

  • Use directly when starting a run with the execution_class attribute of a RunConfiguration object, or
  • Attach it to an instance configuration with the execution_class attribute of an InstanceConfiguration object and use that instance when starting a run.

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

import os

import nextmv
from nextmv import cloud
from nextmv import RunConfiguration

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="glowing-otter")
run_result = app.new_run_with_result(
    input={"name": "world", "radius": 6378, "distance": 147.6},
    instance_id="latest",
    configuration=RunConfiguration(execution_class="6c9500mb870s"),
)

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-48ntXyPvR",
  "metadata": {
    "application_id": "glowing-otter",
    "application_instance_id": "latest",
    "application_version_id": "",
    "created_at": "2026-07-28T19:27:40Z",
    "duration": 6971.0,
    "error": "",
    "execution_class": "6c9500mb870s",
    "execution_duration": 5976.0,
    "format": {
      "input": {
        "type": "json"
      },
      "output": {
        "type": "json"
      }
    },
    "initiated_at": "2026-07-28T19:27:41.132173Z",
    "input_size": 47.0,
    "metrics": {
      "message": "Hello, world",
      "value": 1.23
    },
    "options": {
      "active_options": {
        "details": "true"
      },
      "options_summary": [
        {
          "name": "details",
          "source": "version",
          "value": "true"
        }
      ]
    },
    "output_size": 25099.0,
    "queuing_disabled": false,
    "queuing_priority": 6,
    "run_type": {
      "type": "standard",
      "definition_id": "",
      "reference_id": ""
    },
    "runtime": "python-3_11",
    "status_v2": "succeeded"
  },
  "name": "",
  "user_email": "sebastian@nextmv.io",
  "console_url": "https://cloud.nextmv.io/app/glowing-otter/run/latest-48ntXyPvR?view=details",
  "output": {
    "options": {
      "details": true
    },
    "solution": {
      "message": "Hello, world"
    },
    "metrics": {
      "value": 1.23,
      "message": "Hello, world"
    }
  }
}

Let's say we have an instance identified as production. First, let's update it to use a specific execution class with the Application.update_instance method.

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="glowing-otter")
instance = app.update_instance(
    id="production",
    configuration=cloud.InstanceConfiguration(execution_class="6c9500mb870s"),
)

nextmv.write(instance.to_dict())

uv run main.py

{
  "id": "production",
  "application_id": "glowing-otter",
  "version_id": "v0.0.1",
  "name": "The main production instance",
  "description": "",
  "configuration": {
    "execution_class": "6c9500mb870s",
    "queuing": {
      "priority": 6,
      "disabled": false
    }
  },
  "locked": false,
  "created_at": "2026-07-28T19:27:31.646329Z",
  "updated_at": "2026-07-28T19:28:00.871973Z"
}

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

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="glowing-otter")
run_result = app.new_run_with_result(
    input={"name": "world", "radius": 6378, "distance": 147.6},
    instance_id="production",
)

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": "production-GqghXsPDg",
  "metadata": {
    "application_id": "glowing-otter",
    "application_instance_id": "production",
    "application_version_id": "v0.0.1",
    "created_at": "2026-07-28T19:28:08Z",
    "duration": 5355.0,
    "error": "",
    "execution_class": "6c9500mb870s",
    "execution_duration": 5050.0,
    "format": {
      "input": {
        "type": "json"
      },
      "output": {
        "type": "json"
      }
    },
    "initiated_at": "2026-07-28T19:28:08.892775Z",
    "input_size": 47.0,
    "metrics": {
      "message": "Hello, world",
      "value": 1.23
    },
    "options": {
      "active_options": {
        "details": "true"
      },
      "options_summary": [
        {
          "name": "details",
          "source": "version",
          "value": "true"
        }
      ]
    },
    "output_size": 25099.0,
    "queuing_disabled": false,
    "queuing_priority": 6,
    "run_type": {
      "type": "standard",
      "definition_id": "",
      "reference_id": ""
    },
    "runtime": "python-3_11",
    "status_v2": "succeeded"
  },
  "name": "",
  "user_email": "sebastian@nextmv.io",
  "console_url": "https://cloud.nextmv.io/app/glowing-otter/run/production-GqghXsPDg?view=details",
  "output": {
    "options": {
      "details": true
    },
    "solution": {
      "message": "Hello, world"
    },
    "metrics": {
      "value": 1.23,
      "message": "Hello, world"
    }
  }
}