Skip to main content
A run (also called an execution) is a single, ephemeral invocation of code on Lyceum Cloud. You submit some code or a container, the platform schedules it onto a machine matching the hardware profile you asked for, streams logs back, and bills you per second of wall-clock time. When the code finishes — successfully or otherwise — the machine is released. Runs are the right tool when:
  • The work has a clear start and end (a training step, a batch transform, a one-off job)
  • You don’t need to keep the environment around between invocations
  • You’d rather not manage a long-lived server
For interactive sessions over SSH, use Instances. For long-running model serving, use Dedicated Inference.

​
Execution types

Three submission paths produce the same kind of run record:
TypeWhen to use itEndpoint
PythonA .py file or a snippet, with optional requirements.txt and bundled local importsPOST /execution/streaming/start
Docker imageYou already have a container image with your environment baked inPOST /execution/image/start
Docker ComposeA multi-service stack defined in docker-compose.ymlPOST /execution/compose/start
All three return an execution_id and a streaming URL. From that point on you interact with the run through the same set of read/abort endpoints, regardless of how it was submitted.

​
Lifecycle

A run moves through these states: pending → starting → running → completed (or failed, system_failure, cancelled, aborted) pending and starting cover queueing and machine provisioning. running is what it sounds like. The terminal states are mutually exclusive — aborted means a user (or the API) hard-stopped it, cancelled is a graceful stop (used for notebooks), failed is a non-zero exit, system_failure is an infra problem, and completed is a clean finish. You can list runs by status to monitor the queue or to find recently failed runs to investigate.

​
CLI

lyceum workloads list                       # active runs
lyceum workloads history                    # recent runs
lyceum workloads abort <execution_id>       # hard stop
abort marks the run aborted and kills the underlying job. The graceful-stop variant (which marks the run completed, used for notebook sessions you’re ending normally) is API-only — see the workloads /stop endpoint below.

​
REST API

MethodEndpointPurpose
GET/workloads/listList your executions
GET/execution/{execution_id}Full execution record (status, stdout, stderr, result)
GET/execution/{execution_id}/timingStart, end, duration
GET/execution/{execution_id}/metricsGPU and system metrics
GET/logs/execution/{execution_id}Logs from Loki
POST/workloads/abort/{execution_id}Hard-stop
POST/workloads/stop/{execution_id}Graceful stop
DELETE/execution/{execution_id}Delete the execution record

​
GPU and system metrics

For runs on GPU machines, the platform records per-execution metrics from DCGM and system telemetry. The metrics endpoint exposes:
  • GPU — utilisation %, memory utilisation %, temperature °C, power draw and limit (W), SM and memory clocks (MHz), PCIe RX/TX throughput
  • System — total and used RAM, CPU usage %
The query supports start, end, and step (default 15s) so you can pull the whole run or a window. This is the same data the dashboard charts; you can use it to attribute time, debug stalls, and confirm a job actually used the GPU it was billed for.

​
Logs

Logs are stored in Loki and queryable by execution. By default the logs endpoint returns the last 24 hours of output for an execution (max 10,000 entries) — adjust with limit and hours query parameters.

​
GPU selection runs

In addition to the three standard execution types, Lyceum Cloud supports a GPU selection flow where the platform fans your code out across multiple GPU types and hands back results from each. The use case is benchmarking: you want to know which GPU is fastest or most cost-effective for a given workload before committing to a hardware profile. The flow is asynchronous: you submit code, get back an execution_id plus a callback token, and poll the status endpoint until the parent execution and its sub-jobs complete.

​
CLI

lyceum gpu-selection run script.py
lyceum gpu-selection status <execution_id>

​
REST API

MethodEndpointPurpose
POST/execution/gpu_selection/startSubmit code for GPU selection
GET/execution/gpu_selection/{execution_id}/statusGet the current status of the parent execution and any sub-jobs
The parent execution gets recorded like any other run, and sub-jobs appear as related executions you can query individually.

​
Inspecting an end-to-end workflow

For a worked example that submits a run, polls until it’s done, and pulls logs and metrics, see End-to-End API Workflow.

Launch a run

Submit a Python or Docker workload.

Manage secrets

Inject environment variables into runs.