FleetAgentsClient

Client for the Kibana Fleet Elastic Agents API.

Manages Elastic Agents enrolled in Fleet: listing and inspecting agents, per-agent operations (update, reassign, unenroll, upgrade, request diagnostics, migrate, rollback), bulk variants of those operations, agent action bookkeeping (status, cancel), diagnostics file uploads, agent status summaries, and Fleet agents setup.

Fleet agent APIs are space-scoped: agents are visible in the Kibana space of the agent policy they are assigned to. Every method accepts an optional space_id to target a specific space.

class kibana._sync.client.fleet_agents.FleetAgentsClient(client, default_space_id=None, validate_spaces=True)[source]

Bases: NamespaceClient

Client for the Kibana Fleet Elastic Agents API.

Manages Elastic Agents enrolled in Fleet: listing and inspecting agents, per-agent operations (update, reassign, unenroll, upgrade, request diagnostics, migrate, rollback), bulk variants of those operations, agent action bookkeeping (status, cancel), diagnostics file uploads, agent status summaries, and Fleet agents setup.

Fleet agent APIs are space-scoped: agents are visible in the Kibana space of the agent policy they are assigned to. Every method accepts an optional space_id to target a specific space (None targets the default space or the space the client is scoped to).

Example

>>> from kibana import Kibana
>>> client = Kibana("http://localhost:5601", api_key="...")
>>>
>>> # List enrolled agents and get a status summary
>>> agents = client.fleet_agents.get_all(per_page=50)
>>> summary = client.fleet_agents.get_status()
>>> print(summary.body["results"]["online"])
>>>
>>> # Upgrade every agent on a policy
>>> client.fleet_agents.bulk_upgrade(
...     agents='fleet-agents.policy_id : "my-policy"',
...     version="9.4.3",
... )

Listing Agents and Status Summaries

from kibana import Kibana

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

# List agents with a KQL filter and a status summary
agents = client.fleet_agents.get_all(
    kuery='fleet-agents.status : "online"',
    per_page=50,
    get_status_summary=True,
)
for agent in agents.body["items"]:
    print(agent["id"], agent["status"], agent["policy_id"])

# Aggregate status counts (optionally filtered by policy)
summary = client.fleet_agents.get_status()
print(summary.body["results"]["online"])

# Distinct agent tags and upgradable versions
tags = client.fleet_agents.get_tags()
versions = client.fleet_agents.get_available_versions()

Managing Individual Agents

# Inspect and update a single agent
agent = client.fleet_agents.get(agent_id="agent-id-1", with_metrics=True)
client.fleet_agents.update(
    agent_id="agent-id-1", tags=["production", "linux"]
)

# Reassign to another policy, upgrade, or unenroll
client.fleet_agents.reassign(
    agent_id="agent-id-1", policy_id="agent-policy-id-2"
)
client.fleet_agents.upgrade(agent_id="agent-id-1", version="9.4.3")
client.fleet_agents.unenroll(agent_id="agent-id-1", revoke=True)

Bulk Operations

Bulk methods select agents either by an explicit list of agent IDs or by a KQL query string:

# Upgrade every agent on a policy over one hour
result = client.fleet_agents.bulk_upgrade(
    agents='fleet-agents.policy_id : "my-policy"',
    version="9.4.3",
    rollout_duration_seconds=3600,
)
print(result.body["actionId"])

# Add and remove tags in bulk
client.fleet_agents.bulk_update_tags(
    agents=["agent-id-1", "agent-id-2"],
    tags_to_add=["production"],
    tags_to_remove=["staging"],
)

Agent Actions and Diagnostics

# Request a diagnostics bundle and track the action
created = client.fleet_agents.request_diagnostics(agent_id="agent-id-1")
statuses = client.fleet_agents.get_action_status(per_page=10)

# Cancel an in-progress action
client.fleet_agents.cancel_action(action_id=created.body["actionId"])

# Download and clean up uploaded files
uploads = client.fleet_agents.get_uploads(agent_id="agent-id-1")
for item in uploads.body["items"]:
    content = client.fleet_agents.get_file(
        file_id=item["id"], file_name=item["name"]
    )
    client.fleet_agents.delete_file(file_id=item["id"])

Fleet Setup

setup = client.fleet_agents.get_setup_status()
if not setup.body["isReady"]:
    print(setup.body["missing_requirements"])
client.fleet_agents.initiate_setup()
__init__(client, default_space_id=None, validate_spaces=True)[source]

Initialize the FleetAgentsClient.

Parameters:

  • client (Kibana) – The parent Kibana client 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 before space-scoped operations (default: True).

Example

>>> fleet_agents_client = FleetAgentsClient(kibana_client)
get_status(*, policy_id=None, policy_ids=None, kuery=None, space_id=None, validate_spaces=None)[source]

Get an agent status summary.

Gets a summary of agent statuses (online, offline, error, updating, …), optionally filtered by agent policy.

Parameters:

  • policy_id (str | None) – Filter by a single agent policy ID.

  • policy_ids (list[str] | None) – Filter by one or more agent policy IDs.

  • kuery (str | None) – A KQL query string to filter results.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • results: Per-status agent counts (online, error, offline, updating, inactive, unenrolled, orphaned, uninstalled, all, active, other, events).

Return type:

ObjectApiResponse containing

Raises:

Example

>>> summary = client.fleet_agents.get_status()
>>> print(summary.body["results"]["online"])
5
get_incoming_data(*, agents_ids, pkg_name=None, pkg_version=None, preview_data=None, space_id=None, validate_spaces=None)[source]

Get incoming agent data.

Gets the data streams that the given agents are actively sending data to. Requires the fleet-agents-read privilege.

Parameters:

  • agents_ids (list[str] | str) – Agent IDs to check data for, as a list or a single comma-separated string.

  • pkg_name (str | None) – Filter by integration package name.

  • pkg_version (str | None) – Filter by integration package version.

  • preview_data (bool | None) – When True, return a preview of the ingested data.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • items: One entry per agent ID mapping to {"data": bool}.

  • dataPreview: Preview documents when preview_data is True.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> data = client.fleet_agents.get_incoming_data(
...     agents_ids=["agent-id-1", "agent-id-2"]
... )
>>> print(data.body["items"])
get_all(*, page=None, per_page=None, kuery=None, show_agentless=None, show_inactive=None, with_metrics=None, show_upgradeable=None, get_status_summary=None, sort_field=None, sort_order=None, search_after=None, open_pit=None, pit_id=None, pit_keep_alive=None, space_id=None, validate_spaces=None)[source]

Get agents.

Lists agents, with optional filtering and pagination. Requires the fleet-agents-read privilege.

Parameters:

  • page (int | None) – Page number.

  • per_page (int | None) – Number of results per page (default: 20).

  • kuery (str | None) – A KQL query string to filter results (for example, 'fleet-agents.tags : "production"').

  • show_agentless (bool | None) – When True, include agentless agents in the results (default: True).

  • show_inactive (bool | None) – When True, include inactive agents in the results (default: False).

  • with_metrics (bool | None) – When True, include CPU and memory metrics in the response (default: False).

  • show_upgradeable (bool | None) – When True, only return agents that are upgradeable (default: False).

  • get_status_summary (bool | None) – When True, return a summary of agent statuses in the response (default: False).

  • sort_field (str | None) – Field to sort results by.

  • sort_order (str | None) – Sort order, "asc" or "desc".

  • search_after (str | None) – JSON-encoded array of sort values for search_after pagination.

  • open_pit (bool | None) – When True, opens a new point-in-time for pagination.

  • pit_id (str | None) – Point-in-time ID for pagination.

  • pit_keep_alive (str | None) – Duration to keep the point-in-time alive, for example "1m".

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • items: The list of agents.

  • total / page / perPage: Pagination info.

  • statusSummary: Per-status counts when get_status_summary is True.

  • pit / nextSearchAfter: Pagination cursors when requested.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> agents = client.fleet_agents.get_all(
...     kuery='fleet-agents.status : "online"', per_page=50
... )
>>> for agent in agents.body["items"]:
...     print(agent["id"], agent["status"])
get_by_actions(*, action_ids, space_id=None, validate_spaces=None)[source]

Get agents by action ids.

Retrieves the IDs of agents associated with specific action IDs. Requires the fleet-agents-read privilege.

Parameters:

  • action_ids (list[str]) – The action IDs to look up agents for.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • items: The list of agent IDs associated with the actions.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> agents = client.fleet_agents.get_by_actions(
...     action_ids=["action-id-1", "action-id-2"]
... )
>>> print(agents.body["items"])
get(*, agent_id, with_metrics=None, space_id=None, validate_spaces=None)[source]

Get an agent.

Gets an agent by ID. Requires the fleet-agents-read privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • with_metrics (bool | None) – When True, include CPU and memory metrics in the response (default: False).

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • item: The agent (id, status, policy_id, local_metadata, tags, …).

Return type:

ObjectApiResponse containing

Raises:

Example

>>> agent = client.fleet_agents.get(agent_id="agent-id-1")
>>> print(agent.body["item"]["status"])
online
update(*, agent_id, tags=None, user_provided_metadata=None, space_id=None, validate_spaces=None)[source]

Update an agent.

Updates an agent by ID. Only the user-editable fields (tags and user_provided_metadata) can be changed. Requires the fleet-agents-all privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • tags (list[str] | None) – The list of tags to assign to the agent (replaces the existing tags).

  • user_provided_metadata (dict[str, Any] | None) – User-provided metadata to attach to the agent.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • item: The updated agent.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> updated = client.fleet_agents.update(
...     agent_id="agent-id-1", tags=["production", "linux"]
... )
>>> print(updated.body["item"]["tags"])
['production', 'linux']
delete(*, agent_id, space_id=None, validate_spaces=None)[source]

Delete an agent.

Deletes an agent by ID. This removes the agent document from Fleet; it does not uninstall the Elastic Agent from the host. Requires the fleet-agents-all privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • action: "deleted" on success.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = client.fleet_agents.delete(agent_id="agent-id-1")
>>> print(result.body["action"])
deleted
create_action(*, agent_id, action, space_id=None, validate_spaces=None)[source]

Create an agent action.

Creates an action for the given agent, for example a SETTINGS action to change its log level. Requires the fleet-agents-all privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • action (dict[str, Any]) – The action object. Either {"type": "UNENROLL" | "UPGRADE" | "POLICY_REASSIGN", "data": ..., "ack_data": ...} or {"type": "SETTINGS", "data": {"log_level": "debug" | "info" | "warning" | "error" | None}}.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • item: The created action (id, type, created_at, …).

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = client.fleet_agents.create_action(
...     agent_id="agent-id-1",
...     action={"type": "SETTINGS", "data": {"log_level": "debug"}},
... )
>>> print(result.body["item"]["type"])
SETTINGS
get_effective_config(*, agent_id, space_id=None, validate_spaces=None)[source]

Get an agent’s effective config.

Technical preview in 9.4. Gets the effective (fully resolved) configuration that the agent is running with. Requires the fleet-agents-read privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the agent’s effective configuration document.

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> config = client.fleet_agents.get_effective_config(
...     agent_id="agent-id-1"
... )
migrate(*, agent_id, enrollment_token, uri, settings=None, space_id=None, validate_spaces=None)[source]

Migrate a single agent.

Migrates the agent to another Fleet Server / cluster identified by its URI, enrolling it with the given enrollment token. Requires the fleet-agents-all privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • enrollment_token (str) – The enrollment token to use on the target cluster.

  • uri (str) – The URI of the target Fleet Server (for example, "https://fleet.example.com:8220").

  • settings (dict[str, Any] | None) – Optional migration settings (ca_sha256, certificate_authorities, elastic_agent_cert, elastic_agent_cert_key, elastic_agent_cert_key_passphrase, headers, insecure, proxy_disabled, proxy_headers, proxy_url, replace_token, staging, tags).

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse describing the created migrate action.

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> client.fleet_agents.migrate(
...     agent_id="agent-id-1",
...     enrollment_token="token123",
...     uri="https://fleet.example.com:8220",
... )
change_privilege_level(*, agent_id, user_info=None, space_id=None, validate_spaces=None)[source]

Change agent privilege level.

Changes the privilege level of the agent, for example switching it to run in unprivileged mode. Requires the fleet-agents-all privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • user_info (dict[str, Any] | None) – Optional user information for running the agent unprivileged (username, groupname, password).

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse describing the created privilege-level-change action.

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> client.fleet_agents.change_privilege_level(
...     agent_id="agent-id-1",
...     user_info={"username": "elastic-agent-user"},
... )
reassign(*, agent_id, policy_id, space_id=None, validate_spaces=None)[source]

Reassign an agent.

Reassigns the agent to a different agent policy. Requires the fleet-agents-all privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • policy_id (str) – The ID of the agent policy to assign the agent to.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an empty body on success.

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> client.fleet_agents.reassign(
...     agent_id="agent-id-1", policy_id="agent-policy-id-2"
... )
request_diagnostics(*, agent_id, additional_metrics=None, space_id=None, validate_spaces=None)[source]

Request agent diagnostics.

Requests a diagnostics bundle from the agent. The resulting file upload can be listed with get_uploads() and downloaded with get_file(). Requires the fleet-agents-read privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • additional_metrics (list[str] | None) – Additional metrics to include in the diagnostics bundle (allowed value: "CPU").

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • actionId: The ID of the created request-diagnostics action.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = client.fleet_agents.request_diagnostics(
...     agent_id="agent-id-1", additional_metrics=["CPU"]
... )
>>> print(result.body["actionId"])
rollback(*, agent_id, space_id=None, validate_spaces=None)[source]

Rollback an agent.

Technical preview in 9.4. Rolls the agent back to its previous version after an upgrade. Requires the fleet-agents-all privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse describing the created rollback action.

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> client.fleet_agents.rollback(agent_id="agent-id-1")
unenroll(*, agent_id, force=None, revoke=None, space_id=None, validate_spaces=None)[source]

Unenroll an agent.

Unenrolls the agent from Fleet. The agent stops checking in and its API keys are invalidated. Requires the fleet-agents-all privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • force (bool | None) – When True, unenroll the agent immediately even if it is a hosted (managed) agent.

  • revoke (bool | None) – When True, revoke the agent’s API keys immediately instead of waiting for the agent to acknowledge the action.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an empty body on success.

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> client.fleet_agents.unenroll(agent_id="agent-id-1", revoke=True)
upgrade(*, agent_id, version, source_uri=None, force=None, skip_rate_limit_check=None, space_id=None, validate_spaces=None)[source]

Upgrade an agent.

Upgrades the agent to the given version. Requires the fleet-agents-all privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • version (str) – The version to upgrade the agent to.

  • source_uri (str | None) – Optional URI to download the agent artifact from (instead of the default artifact registry).

  • force (bool | None) – When True, force the upgrade even if the agent is not upgradeable (for example, a hosted agent).

  • skip_rate_limit_check (bool | None) – When True, skip the upgrade rate limit check.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an empty body on success.

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> client.fleet_agents.upgrade(
...     agent_id="agent-id-1", version="9.4.3"
... )
get_uploads(*, agent_id, space_id=None, validate_spaces=None)[source]

Get agent uploads.

Lists the files (for example, diagnostics bundles) uploaded by the agent. Requires the fleet-agents-read privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • items: The list of uploaded files (id, name, filePath, createTime, status, actionId).

Return type:

ObjectApiResponse containing

Raises:

Example

>>> uploads = client.fleet_agents.get_uploads(agent_id="agent-id-1")
>>> for item in uploads.body["items"]:
...     print(item["name"], item["status"])
get_action_status(*, page=None, per_page=None, date=None, latest=None, error_size=None, space_id=None, validate_spaces=None)[source]

Get an agent action status.

Lists the statuses of recent agent actions (upgrades, unenrollments, reassignments, …). Requires the fleet-agents-read privilege.

Parameters:

  • page (int | None) – Page number (default: 0).

  • per_page (int | None) – Number of results per page (default: 20).

  • date (str | None) – Filter actions by date (ISO 8601).

  • latest (int | None) – Return actions created in the latest N milliseconds.

  • error_size (int | None) – Number of latestErrors entries to return per action (default: 5).

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • items: Action statuses (actionId, type, status, nbAgentsActioned, nbAgentsAck, creationTime, latestErrors, …).

Return type:

ObjectApiResponse containing

Raises:

Example

>>> statuses = client.fleet_agents.get_action_status(per_page=10)
>>> for action in statuses.body["items"]:
...     print(action["actionId"], action["type"], action["status"])
cancel_action(*, action_id, space_id=None, validate_spaces=None)[source]

Cancel an agent action.

Cancels an in-progress agent action by its ID. Requires the fleet-agents-all privilege.

Parameters:

  • action_id (str) – The ID of the action to cancel.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • item: The created CANCEL action (id, type, created_at, …).

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = client.fleet_agents.cancel_action(
...     action_id="action-id-1"
... )
>>> print(result.body["item"]["type"])
CANCEL
get_available_versions(*, space_id=None, validate_spaces=None)[source]

Get available agent versions.

Lists the Elastic Agent versions available for upgrades.

Parameters:

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • items: The list of available version strings.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> versions = client.fleet_agents.get_available_versions()
>>> print(versions.body["items"][0])
9.4.3
bulk_migrate(*, agents, enrollment_token, uri, settings=None, batch_size=None, space_id=None, validate_spaces=None)[source]

Migrate multiple agents.

Bulk version of migrate(): migrates the selected agents to another Fleet Server / cluster. Requires the fleet-agents-all privilege.

Parameters:

  • agents (list[str] | str) – Agents to migrate — either a list of agent IDs or a KQL query string selecting agents.

  • enrollment_token (str) – The enrollment token to use on the target cluster.

  • uri (str) – The URI of the target Fleet Server.

  • settings (dict[str, Any] | None) – Optional migration settings (same keys as migrate(), minus replace_token).

  • batch_size (int | None) – Batch size for processing the selected agents.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • actionId: The ID of the created bulk migrate action.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = client.fleet_agents.bulk_migrate(
...     agents=["agent-id-1", "agent-id-2"],
...     enrollment_token="token123",
...     uri="https://fleet.example.com:8220",
... )
>>> print(result.body["actionId"])
bulk_change_privilege_level(*, agents, user_info=None, batch_size=None, space_id=None, validate_spaces=None)[source]

Bulk change agent privilege level.

Bulk version of change_privilege_level(): changes the privilege level of the selected agents. Requires the fleet-agents-all privilege.

Parameters:

  • agents (list[str] | str) – Agents to update — either a list of agent IDs or a KQL query string selecting agents.

  • user_info (dict[str, Any] | None) – Optional user information for running the agents unprivileged (username, groupname, password).

  • batch_size (int | None) – Batch size for processing the selected agents.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • actionId: The ID of the created bulk action.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = client.fleet_agents.bulk_change_privilege_level(
...     agents=["agent-id-1", "agent-id-2"],
...     user_info={"username": "elastic-agent-user"},
... )
>>> print(result.body["actionId"])
bulk_reassign(*, agents, policy_id, batch_size=None, include_inactive=None, space_id=None, validate_spaces=None)[source]

Bulk reassign agents.

Bulk version of reassign(): reassigns the selected agents to a different agent policy. Requires the fleet-agents-all privilege.

Parameters:

  • agents (list[str] | str) – Agents to reassign — either a list of agent IDs or a KQL query string selecting agents.

  • policy_id (str) – The ID of the agent policy to assign the agents to.

  • batch_size (int | None) – Batch size for processing the selected agents.

  • include_inactive (bool | None) – When True, include inactive agents in the selection.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • actionId: The ID of the created bulk reassign action.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = client.fleet_agents.bulk_reassign(
...     agents='fleet-agents.status : "offline"',
...     policy_id="agent-policy-id-2",
... )
>>> print(result.body["actionId"])
bulk_request_diagnostics(*, agents, additional_metrics=None, batch_size=None, space_id=None, validate_spaces=None)[source]

Bulk request diagnostics from agents.

Bulk version of request_diagnostics(): requests diagnostics bundles from the selected agents. Requires the fleet-agents-read privilege.

Parameters:

  • agents (list[str] | str) – Agents to request diagnostics from — either a list of agent IDs or a KQL query string selecting agents.

  • additional_metrics (list[str] | None) – Additional metrics to include in the diagnostics bundles (allowed value: "CPU").

  • batch_size (int | None) – Batch size for processing the selected agents.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • actionId: The ID of the created bulk action.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = client.fleet_agents.bulk_request_diagnostics(
...     agents=["agent-id-1", "agent-id-2"],
...     additional_metrics=["CPU"],
... )
>>> print(result.body["actionId"])
bulk_rollback(*, agents, batch_size=None, include_inactive=None, space_id=None, validate_spaces=None)[source]

Bulk rollback agents.

Technical preview in 9.4. Bulk version of rollback(): rolls the selected agents back to their previous versions. Requires the fleet-agents-all privilege.

Parameters:

  • agents (list[str] | str) – Agents to roll back — either a list of agent IDs or a KQL query string selecting agents.

  • batch_size (int | None) – Batch size for processing the selected agents.

  • include_inactive (bool | None) – When True, include inactive agents in the selection.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • actionIds: The IDs of the created rollback actions (note: unlike the other bulk operations, this endpoint returns a list of action IDs).

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = client.fleet_agents.bulk_rollback(
...     agents=["agent-id-1", "agent-id-2"]
... )
>>> print(result.body["actionIds"])
bulk_unenroll(*, agents, force=None, revoke=None, batch_size=None, include_inactive=None, space_id=None, validate_spaces=None)[source]

Bulk unenroll agents.

Bulk version of unenroll(): unenrolls the selected agents from Fleet. Requires the fleet-agents-all privilege.

Parameters:

  • agents (list[str] | str) – Agents to unenroll — either a list of agent IDs or a KQL query string selecting agents.

  • force (bool | None) – When True, unenroll hosted (managed) agents too.

  • revoke (bool | None) – When True, revoke the agents’ API keys immediately.

  • batch_size (int | None) – Batch size for processing the selected agents.

  • include_inactive (bool | None) – When True, include inactive agents in the selection.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • actionId: The ID of the created bulk unenroll action.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = client.fleet_agents.bulk_unenroll(
...     agents='fleet-agents.status : "inactive"',
...     revoke=True,
...     include_inactive=True,
... )
>>> print(result.body["actionId"])
bulk_update_tags(*, agents, tags_to_add=None, tags_to_remove=None, batch_size=None, include_inactive=None, space_id=None, validate_spaces=None)[source]

Bulk update agent tags.

Adds and/or removes tags on the selected agents. Requires the fleet-agents-all privilege.

Parameters:

  • agents (list[str] | str) – Agents to update — either a list of agent IDs or a KQL query string selecting agents.

  • tags_to_add (list[str] | None) – Tags to add to the selected agents.

  • tags_to_remove (list[str] | None) – Tags to remove from the selected agents.

  • batch_size (int | None) – Batch size for processing the selected agents.

  • include_inactive (bool | None) – When True, include inactive agents in the selection.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • actionId: The ID of the created bulk action.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = client.fleet_agents.bulk_update_tags(
...     agents=["agent-id-1", "agent-id-2"],
...     tags_to_add=["production"],
...     tags_to_remove=["staging"],
... )
>>> print(result.body["actionId"])
bulk_upgrade(*, agents, version, source_uri=None, rollout_duration_seconds=None, start_time=None, force=None, skip_rate_limit_check=None, batch_size=None, include_inactive=None, space_id=None, validate_spaces=None)[source]

Bulk upgrade agents.

Bulk version of upgrade(): upgrades the selected agents to the given version, optionally rolled out over a time window. Requires the fleet-agents-all privilege.

Parameters:

  • agents (list[str] | str) – Agents to upgrade — either a list of agent IDs or a KQL query string selecting agents.

  • version (str) – The version to upgrade the agents to.

  • source_uri (str | None) – Optional URI to download the agent artifact from.

  • rollout_duration_seconds (int | None) – Duration in seconds over which to spread the upgrade rollout.

  • start_time (str | None) – ISO 8601 time at which to start the rollout.

  • force (bool | None) – When True, force the upgrade even for agents that are not upgradeable.

  • skip_rate_limit_check (bool | None) – When True, skip the upgrade rate limit check.

  • batch_size (int | None) – Batch size for processing the selected agents.

  • include_inactive (bool | None) – When True, include inactive agents in the selection.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • actionId: The ID of the created bulk upgrade action.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = client.fleet_agents.bulk_upgrade(
...     agents='fleet-agents.policy_id : "my-policy"',
...     version="9.4.3",
...     rollout_duration_seconds=3600,
... )
>>> print(result.body["actionId"])
get_file(*, file_id, file_name, space_id=None, validate_spaces=None)[source]

Get an uploaded file.

Downloads a file uploaded by an agent (for example, a diagnostics bundle requested with request_diagnostics()). Requires the fleet-agents-read privilege.

Parameters:

  • file_id (str) – The ID of the uploaded file (from get_uploads()).

  • file_name (str) – The name of the uploaded file.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse whose body contains the raw file content.

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> content = client.fleet_agents.get_file(
...     file_id="file-id-1",
...     file_name="elastic-agent-diagnostics.zip",
... )
delete_file(*, file_id, space_id=None, validate_spaces=None)[source]

Delete an uploaded file.

Deletes a file uploaded by an agent. Requires the fleet-agents-all privilege.

Parameters:

  • file_id (str) – The ID of the uploaded file to delete.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • id: The ID of the deleted file.

  • deleted: Whether the file was deleted.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = client.fleet_agents.delete_file(file_id="file-id-1")
>>> print(result.body["deleted"])
True
get_setup_status(*, space_id=None, validate_spaces=None)[source]

Get agent setup info.

Gets a summary of the Fleet agent setup status. isReady indicates whether the setup is ready; if not, missing_requirements lists what is missing (for example, a Fleet Server).

Parameters:

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • isReady: Whether agent setup is ready.

  • missing_requirements: Missing requirements (for example, "fleet_server", "api_keys").

  • missing_optional_features: Missing optional features.

  • is_secrets_storage_enabled / is_space_awareness_enabled / …: Feature flags.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> setup = client.fleet_agents.get_setup_status()
>>> print(setup.body["isReady"])
initiate_setup(*, space_id=None, validate_spaces=None)[source]

Initiate Fleet setup.

Initiates the Fleet agents setup process (creates the required Fleet index templates, packages and policies if missing). This is idempotent: calling it when Fleet is already set up succeeds.

Parameters:

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • isInitialized: Whether Fleet is initialized.

  • nonFatalErrors: Any non-fatal errors hit during setup.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = client.fleet_agents.initiate_setup()
>>> print(result.body["isInitialized"])
True
get_tags(*, kuery=None, show_inactive=None, space_id=None, validate_spaces=None)[source]

Get agent tags.

Lists the distinct tags across agents. Requires the fleet-agents-read privilege.

Parameters:

  • kuery (str | None) – A KQL query string to filter the agents whose tags are aggregated.

  • show_inactive (bool | None) – When True, include tags of inactive agents (default: False).

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • items: The list of distinct tag strings.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> tags = client.fleet_agents.get_tags()
>>> print(tags.body["items"])
['production', 'linux']
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]

AsyncFleetAgentsClient

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

class kibana._async.client.fleet_agents.AsyncFleetAgentsClient(client, default_space_id=None, validate_spaces=True)[source]

Bases: AsyncNamespaceClient

Async client for the Kibana Fleet Elastic Agents API.

Manages Elastic Agents enrolled in Fleet: listing and inspecting agents, per-agent operations (update, reassign, unenroll, upgrade, request diagnostics, migrate, rollback), bulk variants of those operations, agent action bookkeeping (status, cancel), diagnostics file uploads, agent status summaries, and Fleet agents setup.

Fleet agent APIs are space-scoped: agents are visible in the Kibana space of the agent policy they are assigned to. Every method accepts an optional space_id to target a specific space (None targets the default space or the space the client is scoped to).

Example

>>> from kibana import AsyncKibana
>>> client = AsyncKibana("http://localhost:5601", api_key="...")
>>>
>>> # List enrolled agents and get a status summary
>>> agents = await client.fleet_agents.get_all(per_page=50)
>>> summary = await client.fleet_agents.get_status()
>>> print(summary.body["results"]["online"])
>>>
>>> # Upgrade every agent on a policy
>>> await client.fleet_agents.bulk_upgrade(
...     agents='fleet-agents.policy_id : "my-policy"',
...     version="9.4.3",
... )

Usage

The AsyncFleetAgentsClient provides the same methods as FleetAgentsClient 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:
        # List agents (async)
        agents = await client.fleet_agents.get_all(per_page=50)

        # Bulk upgrade (async)
        result = await client.fleet_agents.bulk_upgrade(
            agents='fleet-agents.policy_id : "my-policy"',
            version="9.4.3",
        )

        # Track and cancel the action (async)
        statuses = await client.fleet_agents.get_action_status()
        await client.fleet_agents.cancel_action(
            action_id=result.body["actionId"]
        )

asyncio.run(main())
__init__(client, default_space_id=None, validate_spaces=True)[source]

Initialize the AsyncFleetAgentsClient.

Parameters:

  • client (AsyncKibana) – The parent AsyncKibana client 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 before space-scoped operations (default: True).

Example

>>> fleet_agents_client = AsyncFleetAgentsClient(kibana_client)
async get_status(*, policy_id=None, policy_ids=None, kuery=None, space_id=None, validate_spaces=None)[source]

Get an agent status summary.

Gets a summary of agent statuses (online, offline, error, updating, …), optionally filtered by agent policy.

Parameters:

  • policy_id (str | None) – Filter by a single agent policy ID.

  • policy_ids (list[str] | None) – Filter by one or more agent policy IDs.

  • kuery (str | None) – A KQL query string to filter results.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • results: Per-status agent counts (online, error, offline, updating, inactive, unenrolled, orphaned, uninstalled, all, active, other, events).

Return type:

ObjectApiResponse containing

Raises:

Example

>>> summary = await client.fleet_agents.get_status()
>>> print(summary.body["results"]["online"])
5
async get_incoming_data(*, agents_ids, pkg_name=None, pkg_version=None, preview_data=None, space_id=None, validate_spaces=None)[source]

Get incoming agent data.

Gets the data streams that the given agents are actively sending data to. Requires the fleet-agents-read privilege.

Parameters:

  • agents_ids (list[str] | str) – Agent IDs to check data for, as a list or a single comma-separated string.

  • pkg_name (str | None) – Filter by integration package name.

  • pkg_version (str | None) – Filter by integration package version.

  • preview_data (bool | None) – When True, return a preview of the ingested data.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • items: One entry per agent ID mapping to {"data": bool}.

  • dataPreview: Preview documents when preview_data is True.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> data = await client.fleet_agents.get_incoming_data(
...     agents_ids=["agent-id-1", "agent-id-2"]
... )
>>> print(data.body["items"])
async get_all(*, page=None, per_page=None, kuery=None, show_agentless=None, show_inactive=None, with_metrics=None, show_upgradeable=None, get_status_summary=None, sort_field=None, sort_order=None, search_after=None, open_pit=None, pit_id=None, pit_keep_alive=None, space_id=None, validate_spaces=None)[source]

Get agents.

Lists agents, with optional filtering and pagination. Requires the fleet-agents-read privilege.

Parameters:

  • page (int | None) – Page number.

  • per_page (int | None) – Number of results per page (default: 20).

  • kuery (str | None) – A KQL query string to filter results (for example, 'fleet-agents.tags : "production"').

  • show_agentless (bool | None) – When True, include agentless agents in the results (default: True).

  • show_inactive (bool | None) – When True, include inactive agents in the results (default: False).

  • with_metrics (bool | None) – When True, include CPU and memory metrics in the response (default: False).

  • show_upgradeable (bool | None) – When True, only return agents that are upgradeable (default: False).

  • get_status_summary (bool | None) – When True, return a summary of agent statuses in the response (default: False).

  • sort_field (str | None) – Field to sort results by.

  • sort_order (str | None) – Sort order, "asc" or "desc".

  • search_after (str | None) – JSON-encoded array of sort values for search_after pagination.

  • open_pit (bool | None) – When True, opens a new point-in-time for pagination.

  • pit_id (str | None) – Point-in-time ID for pagination.

  • pit_keep_alive (str | None) – Duration to keep the point-in-time alive, for example "1m".

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • items: The list of agents.

  • total / page / perPage: Pagination info.

  • statusSummary: Per-status counts when get_status_summary is True.

  • pit / nextSearchAfter: Pagination cursors when requested.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> agents = await client.fleet_agents.get_all(
...     kuery='fleet-agents.status : "online"', per_page=50
... )
>>> for agent in agents.body["items"]:
...     print(agent["id"], agent["status"])
async get_by_actions(*, action_ids, space_id=None, validate_spaces=None)[source]

Get agents by action ids.

Retrieves the IDs of agents associated with specific action IDs. Requires the fleet-agents-read privilege.

Parameters:

  • action_ids (list[str]) – The action IDs to look up agents for.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • items: The list of agent IDs associated with the actions.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> agents = await client.fleet_agents.get_by_actions(
...     action_ids=["action-id-1", "action-id-2"]
... )
>>> print(agents.body["items"])
async get(*, agent_id, with_metrics=None, space_id=None, validate_spaces=None)[source]

Get an agent.

Gets an agent by ID. Requires the fleet-agents-read privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • with_metrics (bool | None) – When True, include CPU and memory metrics in the response (default: False).

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • item: The agent (id, status, policy_id, local_metadata, tags, …).

Return type:

ObjectApiResponse containing

Raises:

Example

>>> agent = await client.fleet_agents.get(agent_id="agent-id-1")
>>> print(agent.body["item"]["status"])
online
async update(*, agent_id, tags=None, user_provided_metadata=None, space_id=None, validate_spaces=None)[source]

Update an agent.

Updates an agent by ID. Only the user-editable fields (tags and user_provided_metadata) can be changed. Requires the fleet-agents-all privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • tags (list[str] | None) – The list of tags to assign to the agent (replaces the existing tags).

  • user_provided_metadata (dict[str, Any] | None) – User-provided metadata to attach to the agent.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • item: The updated agent.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> updated = await client.fleet_agents.update(
...     agent_id="agent-id-1", tags=["production", "linux"]
... )
>>> print(updated.body["item"]["tags"])
['production', 'linux']
async delete(*, agent_id, space_id=None, validate_spaces=None)[source]

Delete an agent.

Deletes an agent by ID. This removes the agent document from Fleet; it does not uninstall the Elastic Agent from the host. Requires the fleet-agents-all privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • action: "deleted" on success.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = await client.fleet_agents.delete(agent_id="agent-id-1")
>>> print(result.body["action"])
deleted
async create_action(*, agent_id, action, space_id=None, validate_spaces=None)[source]

Create an agent action.

Creates an action for the given agent, for example a SETTINGS action to change its log level. Requires the fleet-agents-all privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • action (dict[str, Any]) – The action object. Either {"type": "UNENROLL" | "UPGRADE" | "POLICY_REASSIGN", "data": ..., "ack_data": ...} or {"type": "SETTINGS", "data": {"log_level": "debug" | "info" | "warning" | "error" | None}}.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • item: The created action (id, type, created_at, …).

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = await client.fleet_agents.create_action(
...     agent_id="agent-id-1",
...     action={"type": "SETTINGS", "data": {"log_level": "debug"}},
... )
>>> print(result.body["item"]["type"])
SETTINGS
async get_effective_config(*, agent_id, space_id=None, validate_spaces=None)[source]

Get an agent’s effective config.

Technical preview in 9.4. Gets the effective (fully resolved) configuration that the agent is running with. Requires the fleet-agents-read privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the agent’s effective configuration document.

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> config = await client.fleet_agents.get_effective_config(
...     agent_id="agent-id-1"
... )
async migrate(*, agent_id, enrollment_token, uri, settings=None, space_id=None, validate_spaces=None)[source]

Migrate a single agent.

Migrates the agent to another Fleet Server / cluster identified by its URI, enrolling it with the given enrollment token. Requires the fleet-agents-all privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • enrollment_token (str) – The enrollment token to use on the target cluster.

  • uri (str) – The URI of the target Fleet Server (for example, "https://fleet.example.com:8220").

  • settings (dict[str, Any] | None) – Optional migration settings (ca_sha256, certificate_authorities, elastic_agent_cert, elastic_agent_cert_key, elastic_agent_cert_key_passphrase, headers, insecure, proxy_disabled, proxy_headers, proxy_url, replace_token, staging, tags).

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse describing the created migrate action.

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> await client.fleet_agents.migrate(
...     agent_id="agent-id-1",
...     enrollment_token="token123",
...     uri="https://fleet.example.com:8220",
... )
async change_privilege_level(*, agent_id, user_info=None, space_id=None, validate_spaces=None)[source]

Change agent privilege level.

Changes the privilege level of the agent, for example switching it to run in unprivileged mode. Requires the fleet-agents-all privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • user_info (dict[str, Any] | None) – Optional user information for running the agent unprivileged (username, groupname, password).

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse describing the created privilege-level-change action.

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> await client.fleet_agents.change_privilege_level(
...     agent_id="agent-id-1",
...     user_info={"username": "elastic-agent-user"},
... )
async reassign(*, agent_id, policy_id, space_id=None, validate_spaces=None)[source]

Reassign an agent.

Reassigns the agent to a different agent policy. Requires the fleet-agents-all privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • policy_id (str) – The ID of the agent policy to assign the agent to.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an empty body on success.

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> await client.fleet_agents.reassign(
...     agent_id="agent-id-1", policy_id="agent-policy-id-2"
... )
async request_diagnostics(*, agent_id, additional_metrics=None, space_id=None, validate_spaces=None)[source]

Request agent diagnostics.

Requests a diagnostics bundle from the agent. The resulting file upload can be listed with get_uploads() and downloaded with get_file(). Requires the fleet-agents-read privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • additional_metrics (list[str] | None) – Additional metrics to include in the diagnostics bundle (allowed value: "CPU").

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • actionId: The ID of the created request-diagnostics action.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = await client.fleet_agents.request_diagnostics(
...     agent_id="agent-id-1", additional_metrics=["CPU"]
... )
>>> print(result.body["actionId"])
async rollback(*, agent_id, space_id=None, validate_spaces=None)[source]

Rollback an agent.

Technical preview in 9.4. Rolls the agent back to its previous version after an upgrade. Requires the fleet-agents-all privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse describing the created rollback action.

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> await client.fleet_agents.rollback(agent_id="agent-id-1")
async unenroll(*, agent_id, force=None, revoke=None, space_id=None, validate_spaces=None)[source]

Unenroll an agent.

Unenrolls the agent from Fleet. The agent stops checking in and its API keys are invalidated. Requires the fleet-agents-all privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • force (bool | None) – When True, unenroll the agent immediately even if it is a hosted (managed) agent.

  • revoke (bool | None) – When True, revoke the agent’s API keys immediately instead of waiting for the agent to acknowledge the action.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an empty body on success.

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> await client.fleet_agents.unenroll(agent_id="agent-id-1", revoke=True)
async upgrade(*, agent_id, version, source_uri=None, force=None, skip_rate_limit_check=None, space_id=None, validate_spaces=None)[source]

Upgrade an agent.

Upgrades the agent to the given version. Requires the fleet-agents-all privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • version (str) – The version to upgrade the agent to.

  • source_uri (str | None) – Optional URI to download the agent artifact from (instead of the default artifact registry).

  • force (bool | None) – When True, force the upgrade even if the agent is not upgradeable (for example, a hosted agent).

  • skip_rate_limit_check (bool | None) – When True, skip the upgrade rate limit check.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an empty body on success.

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> await client.fleet_agents.upgrade(
...     agent_id="agent-id-1", version="9.4.3"
... )
async get_uploads(*, agent_id, space_id=None, validate_spaces=None)[source]

Get agent uploads.

Lists the files (for example, diagnostics bundles) uploaded by the agent. Requires the fleet-agents-read privilege.

Parameters:

  • agent_id (str) – The agent ID.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • items: The list of uploaded files (id, name, filePath, createTime, status, actionId).

Return type:

ObjectApiResponse containing

Raises:

Example

>>> uploads = await client.fleet_agents.get_uploads(agent_id="agent-id-1")
>>> for item in uploads.body["items"]:
...     print(item["name"], item["status"])
async get_action_status(*, page=None, per_page=None, date=None, latest=None, error_size=None, space_id=None, validate_spaces=None)[source]

Get an agent action status.

Lists the statuses of recent agent actions (upgrades, unenrollments, reassignments, …). Requires the fleet-agents-read privilege.

Parameters:

  • page (int | None) – Page number (default: 0).

  • per_page (int | None) – Number of results per page (default: 20).

  • date (str | None) – Filter actions by date (ISO 8601).

  • latest (int | None) – Return actions created in the latest N milliseconds.

  • error_size (int | None) – Number of latestErrors entries to return per action (default: 5).

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • items: Action statuses (actionId, type, status, nbAgentsActioned, nbAgentsAck, creationTime, latestErrors, …).

Return type:

ObjectApiResponse containing

Raises:

Example

>>> statuses = await client.fleet_agents.get_action_status(per_page=10)
>>> for action in statuses.body["items"]:
...     print(action["actionId"], action["type"], action["status"])
async cancel_action(*, action_id, space_id=None, validate_spaces=None)[source]

Cancel an agent action.

Cancels an in-progress agent action by its ID. Requires the fleet-agents-all privilege.

Parameters:

  • action_id (str) – The ID of the action to cancel.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • item: The created CANCEL action (id, type, created_at, …).

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = await client.fleet_agents.cancel_action(
...     action_id="action-id-1"
... )
>>> print(result.body["item"]["type"])
CANCEL
async get_available_versions(*, space_id=None, validate_spaces=None)[source]

Get available agent versions.

Lists the Elastic Agent versions available for upgrades.

Parameters:

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • items: The list of available version strings.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> versions = await client.fleet_agents.get_available_versions()
>>> print(versions.body["items"][0])
9.4.3
async bulk_migrate(*, agents, enrollment_token, uri, settings=None, batch_size=None, space_id=None, validate_spaces=None)[source]

Migrate multiple agents.

Bulk version of migrate(): migrates the selected agents to another Fleet Server / cluster. Requires the fleet-agents-all privilege.

Parameters:

  • agents (list[str] | str) – Agents to migrate — either a list of agent IDs or a KQL query string selecting agents.

  • enrollment_token (str) – The enrollment token to use on the target cluster.

  • uri (str) – The URI of the target Fleet Server.

  • settings (dict[str, Any] | None) – Optional migration settings (same keys as migrate(), minus replace_token).

  • batch_size (int | None) – Batch size for processing the selected agents.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • actionId: The ID of the created bulk migrate action.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = await client.fleet_agents.bulk_migrate(
...     agents=["agent-id-1", "agent-id-2"],
...     enrollment_token="token123",
...     uri="https://fleet.example.com:8220",
... )
>>> print(result.body["actionId"])
async bulk_change_privilege_level(*, agents, user_info=None, batch_size=None, space_id=None, validate_spaces=None)[source]

Bulk change agent privilege level.

Bulk version of change_privilege_level(): changes the privilege level of the selected agents. Requires the fleet-agents-all privilege.

Parameters:

  • agents (list[str] | str) – Agents to update — either a list of agent IDs or a KQL query string selecting agents.

  • user_info (dict[str, Any] | None) – Optional user information for running the agents unprivileged (username, groupname, password).

  • batch_size (int | None) – Batch size for processing the selected agents.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • actionId: The ID of the created bulk action.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = await client.fleet_agents.bulk_change_privilege_level(
...     agents=["agent-id-1", "agent-id-2"],
...     user_info={"username": "elastic-agent-user"},
... )
>>> print(result.body["actionId"])
async bulk_reassign(*, agents, policy_id, batch_size=None, include_inactive=None, space_id=None, validate_spaces=None)[source]

Bulk reassign agents.

Bulk version of reassign(): reassigns the selected agents to a different agent policy. Requires the fleet-agents-all privilege.

Parameters:

  • agents (list[str] | str) – Agents to reassign — either a list of agent IDs or a KQL query string selecting agents.

  • policy_id (str) – The ID of the agent policy to assign the agents to.

  • batch_size (int | None) – Batch size for processing the selected agents.

  • include_inactive (bool | None) – When True, include inactive agents in the selection.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • actionId: The ID of the created bulk reassign action.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = await client.fleet_agents.bulk_reassign(
...     agents='fleet-agents.status : "offline"',
...     policy_id="agent-policy-id-2",
... )
>>> print(result.body["actionId"])
async bulk_request_diagnostics(*, agents, additional_metrics=None, batch_size=None, space_id=None, validate_spaces=None)[source]

Bulk request diagnostics from agents.

Bulk version of request_diagnostics(): requests diagnostics bundles from the selected agents. Requires the fleet-agents-read privilege.

Parameters:

  • agents (list[str] | str) – Agents to request diagnostics from — either a list of agent IDs or a KQL query string selecting agents.

  • additional_metrics (list[str] | None) – Additional metrics to include in the diagnostics bundles (allowed value: "CPU").

  • batch_size (int | None) – Batch size for processing the selected agents.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • actionId: The ID of the created bulk action.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = await client.fleet_agents.bulk_request_diagnostics(
...     agents=["agent-id-1", "agent-id-2"],
...     additional_metrics=["CPU"],
... )
>>> print(result.body["actionId"])
async bulk_rollback(*, agents, batch_size=None, include_inactive=None, space_id=None, validate_spaces=None)[source]

Bulk rollback agents.

Technical preview in 9.4. Bulk version of rollback(): rolls the selected agents back to their previous versions. Requires the fleet-agents-all privilege.

Parameters:

  • agents (list[str] | str) – Agents to roll back — either a list of agent IDs or a KQL query string selecting agents.

  • batch_size (int | None) – Batch size for processing the selected agents.

  • include_inactive (bool | None) – When True, include inactive agents in the selection.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • actionIds: The IDs of the created rollback actions (note: unlike the other bulk operations, this endpoint returns a list of action IDs).

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = await client.fleet_agents.bulk_rollback(
...     agents=["agent-id-1", "agent-id-2"]
... )
>>> print(result.body["actionIds"])
async bulk_unenroll(*, agents, force=None, revoke=None, batch_size=None, include_inactive=None, space_id=None, validate_spaces=None)[source]

Bulk unenroll agents.

Bulk version of unenroll(): unenrolls the selected agents from Fleet. Requires the fleet-agents-all privilege.

Parameters:

  • agents (list[str] | str) – Agents to unenroll — either a list of agent IDs or a KQL query string selecting agents.

  • force (bool | None) – When True, unenroll hosted (managed) agents too.

  • revoke (bool | None) – When True, revoke the agents’ API keys immediately.

  • batch_size (int | None) – Batch size for processing the selected agents.

  • include_inactive (bool | None) – When True, include inactive agents in the selection.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • actionId: The ID of the created bulk unenroll action.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = await client.fleet_agents.bulk_unenroll(
...     agents='fleet-agents.status : "inactive"',
...     revoke=True,
...     include_inactive=True,
... )
>>> print(result.body["actionId"])
async bulk_update_tags(*, agents, tags_to_add=None, tags_to_remove=None, batch_size=None, include_inactive=None, space_id=None, validate_spaces=None)[source]

Bulk update agent tags.

Adds and/or removes tags on the selected agents. Requires the fleet-agents-all privilege.

Parameters:

  • agents (list[str] | str) – Agents to update — either a list of agent IDs or a KQL query string selecting agents.

  • tags_to_add (list[str] | None) – Tags to add to the selected agents.

  • tags_to_remove (list[str] | None) – Tags to remove from the selected agents.

  • batch_size (int | None) – Batch size for processing the selected agents.

  • include_inactive (bool | None) – When True, include inactive agents in the selection.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • actionId: The ID of the created bulk action.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = await client.fleet_agents.bulk_update_tags(
...     agents=["agent-id-1", "agent-id-2"],
...     tags_to_add=["production"],
...     tags_to_remove=["staging"],
... )
>>> print(result.body["actionId"])
async bulk_upgrade(*, agents, version, source_uri=None, rollout_duration_seconds=None, start_time=None, force=None, skip_rate_limit_check=None, batch_size=None, include_inactive=None, space_id=None, validate_spaces=None)[source]

Bulk upgrade agents.

Bulk version of upgrade(): upgrades the selected agents to the given version, optionally rolled out over a time window. Requires the fleet-agents-all privilege.

Parameters:

  • agents (list[str] | str) – Agents to upgrade — either a list of agent IDs or a KQL query string selecting agents.

  • version (str) – The version to upgrade the agents to.

  • source_uri (str | None) – Optional URI to download the agent artifact from.

  • rollout_duration_seconds (int | None) – Duration in seconds over which to spread the upgrade rollout.

  • start_time (str | None) – ISO 8601 time at which to start the rollout.

  • force (bool | None) – When True, force the upgrade even for agents that are not upgradeable.

  • skip_rate_limit_check (bool | None) – When True, skip the upgrade rate limit check.

  • batch_size (int | None) – Batch size for processing the selected agents.

  • include_inactive (bool | None) – When True, include inactive agents in the selection.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • actionId: The ID of the created bulk upgrade action.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = await client.fleet_agents.bulk_upgrade(
...     agents='fleet-agents.policy_id : "my-policy"',
...     version="9.4.3",
...     rollout_duration_seconds=3600,
... )
>>> print(result.body["actionId"])
async get_file(*, file_id, file_name, space_id=None, validate_spaces=None)[source]

Get an uploaded file.

Downloads a file uploaded by an agent (for example, a diagnostics bundle requested with request_diagnostics()). Requires the fleet-agents-read privilege.

Parameters:

  • file_id (str) – The ID of the uploaded file (from get_uploads()).

  • file_name (str) – The name of the uploaded file.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse whose body contains the raw file content.

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> content = await client.fleet_agents.get_file(
...     file_id="file-id-1",
...     file_name="elastic-agent-diagnostics.zip",
... )
async delete_file(*, file_id, space_id=None, validate_spaces=None)[source]

Delete an uploaded file.

Deletes a file uploaded by an agent. Requires the fleet-agents-all privilege.

Parameters:

  • file_id (str) – The ID of the uploaded file to delete.

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • id: The ID of the deleted file.

  • deleted: Whether the file was deleted.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = await client.fleet_agents.delete_file(file_id="file-id-1")
>>> print(result.body["deleted"])
True
async get_setup_status(*, space_id=None, validate_spaces=None)[source]

Get agent setup info.

Gets a summary of the Fleet agent setup status. isReady indicates whether the setup is ready; if not, missing_requirements lists what is missing (for example, a Fleet Server).

Parameters:

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • isReady: Whether agent setup is ready.

  • missing_requirements: Missing requirements (for example, "fleet_server", "api_keys").

  • missing_optional_features: Missing optional features.

  • is_secrets_storage_enabled / is_space_awareness_enabled / …: Feature flags.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> setup = await client.fleet_agents.get_setup_status()
>>> print(setup.body["isReady"])
async initiate_setup(*, space_id=None, validate_spaces=None)[source]

Initiate Fleet setup.

Initiates the Fleet agents setup process (creates the required Fleet index templates, packages and policies if missing). This is idempotent: calling it when Fleet is already set up succeeds.

Parameters:

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • isInitialized: Whether Fleet is initialized.

  • nonFatalErrors: Any non-fatal errors hit during setup.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> result = await client.fleet_agents.initiate_setup()
>>> print(result.body["isInitialized"])
True
async get_tags(*, kuery=None, show_inactive=None, space_id=None, validate_spaces=None)[source]

Get agent tags.

Lists the distinct tags across agents. Requires the fleet-agents-read privilege.

Parameters:

  • kuery (str | None) – A KQL query string to filter the agents whose tags are aggregated.

  • show_inactive (bool | None) – When True, include tags of inactive agents (default: False).

  • space_id (str | None) – Optional space ID to scope the operation to.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • items: The list of distinct tag strings.

Return type:

ObjectApiResponse containing

Raises:

Example

>>> tags = await client.fleet_agents.get_tags()
>>> print(tags.body["items"])
['production', 'linux']
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]