MlClient¶

Client for the Kibana Machine Learning API.

Provides access to the machine learning saved objects APIs, which keep Kibana saved objects in sync with machine learning jobs and trained models, and manage the Kibana spaces those objects belong to.

All operations are space-scoped: pass space_id to target a specific Kibana space, or omit it to target the default space.

class kibana._sync.client.ml.MlClient(client, default_space_id=None, validate_spaces=True)[source]¶

Bases: NamespaceClient

Client for the Kibana Machine Learning API.

All operations are space-scoped: pass space_id to target a specific Kibana space, or omit it to target the default space.

Example

>>> from kibana import Kibana
>>> client = Kibana("http://localhost:5601", api_key="...")
>>>
>>> # Simulate a sync to see what would change
>>> result = client.ml.sync(simulate=True)
>>> print(result.body["savedObjectsCreated"])

Syncing Saved Objects

Synchronize Kibana saved objects for machine learning jobs and trained models with sync():

from kibana import Kibana

client = Kibana("http://localhost:5601", api_key="your_api_key")

# Simulate first to see what would change
result = client.ml.sync(simulate=True)
print(result.body["savedObjectsCreated"])

# Then run the sync for real
result = client.ml.sync()

Managing Job and Model Spaces

Move machine learning jobs and trained models between Kibana spaces:

# Add anomaly detection jobs to a space, remove them from another
client.ml.update_jobs_spaces(
    job_ids=["my-job"],
    job_type="anomaly-detector",
    spaces_to_add=["marketing"],
    spaces_to_remove=["default"],
)

# Same for trained models
client.ml.update_trained_models_spaces(
    model_ids=["my-model"],
    spaces_to_add=["marketing"],
    spaces_to_remove=[],
)

sync(*, simulate=None, space_id=None, validate_spaces=None)[source]¶

Sync machine learning saved objects.

Synchronizes Kibana saved objects for machine learning jobs and trained models. You must have all privileges for the Machine Learning feature in the Analytics section of the Kibana feature privileges. This API runs automatically when you start Kibana and periodically thereafter.

Parameters:

simulate (bool | None) – When True, simulates the synchronization by returning only the list of actions that would be performed.
space_id (str | None) – Optional space ID to scope the operation to. None targets the default space.
validate_spaces (bool | None) – Override the client-level space validation setting for this call.

Returns:

savedObjectsCreated: Saved objects created for jobs or trained models that were missing them.
savedObjectsDeleted: Saved objects deleted because the referenced job or trained model no longer exists.
datafeedsAdded: Datafeed identifiers added to anomaly detection job saved objects that were missing them.
datafeedsRemoved: Datafeed identifiers removed because the datafeed no longer exists.

Return type:

ObjectApiResponse with the sync results

Raises:

AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.

Example

>>> # Dry run: list actions without performing them
>>> result = client.ml.sync(simulate=True)
>>> print(result.body["savedObjectsCreated"])
>>>
>>> # Perform the synchronization in the "marketing" space
>>> result = client.ml.sync(space_id="marketing")

update_jobs_spaces(*, job_ids, job_type, spaces_to_add, spaces_to_remove, space_id=None, validate_spaces=None)[source]¶

Update the spaces assigned to machine learning jobs.

Updates a list of machine learning jobs to add and/or remove them from the given Kibana spaces.

Parameters:

job_ids (list[str]) – Identifiers of the jobs to update.
job_type (str) – Type of the jobs: "anomaly-detector" or "data-frame-analytics".
spaces_to_add (list[str]) – Space IDs to add the jobs to (may be empty).
spaces_to_remove (list[str]) – Space IDs to remove the jobs from (["*"] removes them from all current spaces; may be empty).
space_id (str | None) – Optional space ID to scope the operation to. None targets the default space.
validate_spaces (bool | None) – Override the client-level space validation setting for this call.

Returns:

ObjectApiResponse mapping each job ID to its result, e.g. {"my-job": {"success": True, "type": "anomaly-detector"}}. Failures are reported per job with success: False and an error message, while the HTTP status remains 200.

Raises:

BadRequestError – If the request body fails validation (e.g. an unknown job_type).
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.

Return type:

ObjectApiResponse[Any]

Example

>>> result = client.ml.update_jobs_spaces(
...     job_ids=["my-job"],
...     job_type="anomaly-detector",
...     spaces_to_add=["marketing"],
...     spaces_to_remove=[],
... )
>>> print(result.body["my-job"]["success"])

update_trained_models_spaces(*, model_ids, spaces_to_add, spaces_to_remove, space_id=None, validate_spaces=None)[source]¶

Update the spaces assigned to trained models.

Updates a list of trained models to add and/or remove them from the given Kibana spaces.

Parameters:

model_ids (list[str]) – Identifiers of the trained models to update.
spaces_to_add (list[str]) – Space IDs to add the models to (may be empty).
spaces_to_remove (list[str]) – Space IDs to remove the models from (["*"] removes them from all current spaces; may be empty).
space_id (str | None) – Optional space ID to scope the operation to. None targets the default space.
validate_spaces (bool | None) – Override the client-level space validation setting for this call.

Returns:

ObjectApiResponse mapping each model ID to its result, e.g. {"my-model": {"success": True, "type": "trained-model"}}. Failures are reported per model with success: False and an error message, while the HTTP status remains 200.

Raises:

BadRequestError – If the request body fails validation.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.

Return type:

ObjectApiResponse[Any]

Example

>>> result = client.ml.update_trained_models_spaces(
...     model_ids=["my-model"],
...     spaces_to_add=["marketing"],
...     spaces_to_remove=[],
... )
>>> print(result.body["my-model"]["success"])

__init__(client, default_space_id=None, validate_spaces=True)¶

Initialize NamespaceClient with optional space support.

Parameters:

client (BaseClient) – Parent BaseClient instance to delegate requests to
default_space_id (str | None) – Optional default space ID for all operations
validate_spaces (bool) – Whether to validate space existence (default: True)

perform_request(method, path, *, params=None, headers=None, body=None)¶

Perform an HTTP request via the parent client with space context enhancement.

Parameters:

method (str) – HTTP method (GET, POST, PUT, DELETE, etc.)
path (str) – API endpoint path
params (dict[str, Any] | None) – Query parameters
headers (dict[str, str] | None) – Request headers
body (dict[str, Any] | None) – Request body

Returns:

API response

Raises:

ApiError – If the API returns an error response (enhanced with space context)

Return type:

ObjectApiResponse[Any]

AsyncMlClient¶

Asynchronous version of the MlClient for use with async/await syntax.

class kibana._async.client.ml.AsyncMlClient(client, default_space_id=None, validate_spaces=True)[source]¶

Bases: AsyncNamespaceClient

Async client for the Kibana Machine Learning API.

All operations are space-scoped: pass space_id to target a specific Kibana space, or omit it to target the default space.

Example

>>> from kibana import AsyncKibana
>>> client = AsyncKibana("http://localhost:5601", api_key="...")
>>>
>>> # Simulate a sync to see what would change
>>> result = await client.ml.sync(simulate=True)
>>> print(result.body["savedObjectsCreated"])

Usage

The AsyncMlClient provides the same methods as MlClient but all methods are async and must be awaited:

from kibana import AsyncKibana
import asyncio

async def main():
    async with AsyncKibana("http://localhost:5601") as client:
        # Simulate a sync (async)
        result = await client.ml.sync(simulate=True)
        print(result.body)

asyncio.run(main())

async sync(*, simulate=None, space_id=None, validate_spaces=None)[source]¶

Sync machine learning saved objects.

Parameters:

simulate (bool | None) – When True, simulates the synchronization by returning only the list of actions that would be performed.
space_id (str | None) – Optional space ID to scope the operation to. None targets the default space.
validate_spaces (bool | None) – Override the client-level space validation setting for this call.

Returns:

savedObjectsCreated: Saved objects created for jobs or trained models that were missing them.
savedObjectsDeleted: Saved objects deleted because the referenced job or trained model no longer exists.
datafeedsAdded: Datafeed identifiers added to anomaly detection job saved objects that were missing them.
datafeedsRemoved: Datafeed identifiers removed because the datafeed no longer exists.

Return type:

ObjectApiResponse with the sync results

Raises:

AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.

Example

>>> # Dry run: list actions without performing them
>>> result = await client.ml.sync(simulate=True)
>>> print(result.body["savedObjectsCreated"])
>>>
>>> # Perform the synchronization in the "marketing" space
>>> result = await client.ml.sync(space_id="marketing")

async update_jobs_spaces(*, job_ids, job_type, spaces_to_add, spaces_to_remove, space_id=None, validate_spaces=None)[source]¶

Update the spaces assigned to machine learning jobs.

Updates a list of machine learning jobs to add and/or remove them from the given Kibana spaces.

Parameters:

job_ids (list[str]) – Identifiers of the jobs to update.
job_type (str) – Type of the jobs: "anomaly-detector" or "data-frame-analytics".
spaces_to_add (list[str]) – Space IDs to add the jobs to (may be empty).
spaces_to_remove (list[str]) – Space IDs to remove the jobs from (["*"] removes them from all current spaces; may be empty).
space_id (str | None) – Optional space ID to scope the operation to. None targets the default space.
validate_spaces (bool | None) – Override the client-level space validation setting for this call.

Returns:

Raises:

BadRequestError – If the request body fails validation (e.g. an unknown job_type).
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.

Return type:

ObjectApiResponse[Any]

Example

>>> result = await client.ml.update_jobs_spaces(
...     job_ids=["my-job"],
...     job_type="anomaly-detector",
...     spaces_to_add=["marketing"],
...     spaces_to_remove=[],
... )
>>> print(result.body["my-job"]["success"])

async update_trained_models_spaces(*, model_ids, spaces_to_add, spaces_to_remove, space_id=None, validate_spaces=None)[source]¶

Update the spaces assigned to trained models.

Updates a list of trained models to add and/or remove them from the given Kibana spaces.

Parameters:

model_ids (list[str]) – Identifiers of the trained models to update.
spaces_to_add (list[str]) – Space IDs to add the models to (may be empty).
spaces_to_remove (list[str]) – Space IDs to remove the models from (["*"] removes them from all current spaces; may be empty).
space_id (str | None) – Optional space ID to scope the operation to. None targets the default space.
validate_spaces (bool | None) – Override the client-level space validation setting for this call.

Returns:

Raises:

BadRequestError – If the request body fails validation.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.

Return type:

ObjectApiResponse[Any]

Example

>>> result = await client.ml.update_trained_models_spaces(
...     model_ids=["my-model"],
...     spaces_to_add=["marketing"],
...     spaces_to_remove=[],
... )
>>> print(result.body["my-model"]["success"])

__init__(client, default_space_id=None, validate_spaces=True)¶

Initialize AsyncNamespaceClient with optional space support.

Parameters:

client (AsyncBaseClient) – Parent AsyncBaseClient instance to delegate requests to
default_space_id (str | None) – Optional default space ID for all operations
validate_spaces (bool) – Whether to validate space existence (default: True)

async perform_request(method, path, *, params=None, headers=None, body=None)¶

Perform an async HTTP request via the parent client with space context enhancement.

Parameters:

method (str) – HTTP method (GET, POST, PUT, DELETE, etc.)
path (str) – API endpoint path
params (dict[str, Any] | None) – Query parameters
headers (dict[str, str] | None) – Request headers
body (dict[str, Any] | None) – Request body

Returns:

API response

Raises:

ApiError – If the API returns an error response (enhanced with space context)

Return type:

ObjectApiResponse[Any]