Using the API Client

The Scaleout Edge API Client is the primary programmatic interface for interacting with the Scaleout Edge API.

While the UI is excellent for monitoring, the API Client allows you to automate your MLOps workflows, integrate with CI/CD pipelines, and build custom dashboards.

Installation

The client is available as a standard Python package.

$ pip install scaleout

Connecting to the API

To initialize the connection to the Scaleout Edge API, create an instance of the Scaleout class with your deployment URL and an API key.

API keys are the recommended credential for programmatic and CI/CD use — they are long-lived and do not need to be refreshed. You can create one from the Settings tab in the Dashboard.

>>> from scaleout import Scaleout
>>> client = Scaleout(host="<API-URL>", token="<API-KEY>")

For scripts and automation, the API key can be supplied via an environment variable instead of hardcoding it:

$ export SCALEOUT_AUTH_TOKEN=<api-key>

>>> from scaleout import Scaleout
>>> client = Scaleout(host="<API-URL>")

We are now ready to work with the API.

Uploading a Model

Before starting training, an initial global model must be uploaded to the Control Plane. Use set_active_model to upload a local model file and register it as the active model.

Supported file formats are .npz (NumPy) and .bin (binary):

>>> result = client.set_active_model("path/to/initial_model.npz")
>>> print(result)
{'committed_at': '...', 'id': '...', 'key': 'models', 'model': '...', ...}

The method detects the file format from the extension and sets the matching helper (numpyhelper for .npz, binaryhelper for .bin) automatically.

Orchestrating Sessions

The most common task is automating the training lifecycle.

Starting a session

You can initiate a training run with a specific configuration.

session_config = {
 "name": "nightly-retrain-v2",
 "rounds": 5,
 "min_clients": 10,
 "aggregator": "fedopt",
 "aggregator_kwargs": {
     "learning_rate": 0.01
   }
}

session = client.start_session(**session_config)
print(f"Session started: {session['id']}")

Monitoring Progress

You can poll the session status to wait for completion.

import time

while True:
    status = client.get_controller_status()
    if status == 'idle':
        print("Training complete.")
        break
    time.sleep(60)  # Wait for 1 minute before checking again

Validating a Model

You can trigger a validation of a specific model within a session.

>>> client.start_validation(session_id="<session-id>", model_id="<model-id>")

Managing Combiners

For deployments where a combiner must be reachable at a specific public address, you can set it. Give the hostname and port, as hostname:port, of the endpoint that accepts the edge clients’ gRPC connections, such as a configured ingress or load balancer. Without a port, edge clients connect on the combiner’s portnumber which is normally not exposed directly. For IPv6, use [address]:port.

>>> client.set_public_hostname(id="<combiner-id>", public_hostname="combiner.example.com:443")

List data

Other than orchestrating sessions, the Scaleout client can be used to retrieve information about various entities from the network, such as sessions, models, etc. All entities are represented, and they all work in a similar fashion.

  • get_*() - (plural) list all entities of a specific type

  • get_*(id=<id-of-entity>) - get a specific entity

Entities represented in the Scaleout client are:

  • clients

  • combiners

  • models

  • packages

  • rounds

  • sessions

  • statuses

  • validations

To list all sessions:

>>> sessions = client.get_sessions()

To get a specific session:

>>> session = client.get_session(id="session_id")

For more information on how to use the Scaleout client, see the scaleoututil.api.client.