ApmClient¶

Client for the Kibana APM (Application Performance Monitoring) API.

Covers the Kibana 9.4 APM UI endpoints: APM agent keys, APM Server schema, service annotations, agent configurations, and RUM source maps.

The endpoints are space-scoped: every method accepts an optional space_id to route the request through the /s/{space_id} path prefix. Note that agent configurations and source maps live in cluster-wide storage (the .apm-agent-configuration index and Fleet artifacts), so the same data is visible from every space; the space prefix scopes the API route and its privilege checks rather than the data.

Required privileges vary per endpoint: agent configuration and source map writes need APM/APM settings write privileges; creating agent keys additionally requires the manage_own_api_key cluster privilege.

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

Bases: NamespaceClient

Client for the Kibana APM (Application Performance Monitoring) API.

Covers the Kibana 9.4.3 APM UI endpoints: APM agent keys, APM Server schema, service annotations, agent configurations, and RUM source maps.

The endpoints are space-scoped: every method accepts an optional space_id to route the request through the /s/{space_id} path prefix (None targets the default space or the space the client is scoped to). Note that agent configurations and source maps live in cluster-wide storage (the .apm-agent-configuration index and Fleet artifacts), so the same data is visible from every space; the space prefix scopes the API route and its privilege checks rather than the data.

Example

>>> from kibana import Kibana
>>> client = Kibana("http://localhost:5601", api_key="...")
>>>
>>> # Create an agent configuration
>>> client.apm.create_or_update_agent_configuration(
...     service_name="opbeans-node",
...     service_environment="production",
...     settings={"transaction_sample_rate": "0.5"},
... )
>>>
>>> # List agent configurations
>>> for c in client.apm.get_agent_configurations().body["configurations"]:
...     print(c["service"], c["settings"])

Agent Configurations

Centrally manage APM agent settings:

from kibana import Kibana

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

# Create or update an agent configuration
client.apm.create_or_update_agent_configuration(
    service_name="opbeans-node",
    service_environment="production",
    settings={"transaction_sample_rate": "0.5"},
)

# List agent configurations
for c in client.apm.get_agent_configurations().body["configurations"]:
    print(c["service"], c["settings"])

# Delete an agent configuration
client.apm.delete_agent_configuration(
    service_name="opbeans-node",
    service_environment="production",
)

Agent Keys

# Create an APM agent key (requires manage_own_api_key)
key = client.apm.create_agent_key(
    name="my-agent-key",
    privileges=["event:write", "config_agent:read"],
)

Service Annotations

Mark deployments and other events on APM charts:

# Create a deployment annotation
client.apm.create_annotation(
    service_name="opbeans-node",
    timestamp="2026-07-03T12:00:00.000Z",
    service_version="1.2.3",
    message="Deployed 1.2.3",
)

# Search annotations for a service
annotations = client.apm.search_annotations(
    service_name="opbeans-node",
    environment="production",
)

RUM Source Maps

# List uploaded source maps
sourcemaps = client.apm.get_sourcemaps()

create_agent_key(*, name, privileges, space_id=None, validate_spaces=None)[source]¶

Create an APM agent key.

Create a new agent key for APM. The user creating the key must have the manage_own_api_key cluster privilege and event:write / config_agent:read APM application privileges (superusers qualify). The key secret is returned only once, in the response.

Parameters:

name (str) – The name of the APM agent key.
privileges (list[str]) – The APM agent key privileges. One or more of "event:write" (required for ingesting APM agent events) and "config_agent:read" (required for APM agents to read agent configuration remotely).
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an agentKey object containing id, name, api_key and encoded (the base64 credentials).

Raises:

BadRequestError – If the request body is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks the required privileges to create APM agent keys.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> response = client.apm.create_agent_key(
...     name="my-agent-key",
...     privileges=["event:write", "config_agent:read"],
... )
>>> print(response.body["agentKey"]["encoded"])

save_server_schema(*, schema, space_id=None, validate_spaces=None)[source]¶

Save APM Server schema.

Deprecated since version 9.4: This endpoint is deprecated. It supports the APM Server to Fleet migration workflow in the Applications UI; manage the APM integration policy through Fleet instead.

Save the APM Server settings schema used when migrating a standalone APM Server to a Fleet-managed APM integration.

Parameters:

schema (dict[str, Any]) – Schema object with APM Server settings (arbitrary key/value pairs, e.g. {"apm-server.host": "0.0.0.0:8200"}).
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an empty body on success.

Raises:

BadRequestError – If the request body is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM settings write privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> client.apm.save_server_schema(
...     schema={"apm-server.host": "0.0.0.0:8200"}
... )

create_annotation(*, service_name, timestamp, service_version, service_environment=None, message=None, tags=None, space_id=None, validate_spaces=None)[source]¶

Create a service annotation.

Create a new annotation (e.g. a deployment marker) for a specific service. Annotations are stored in the observability-annotations index and rendered in the Applications UI charts.

Parameters:

service_name (str) – The name of the service (URL path parameter).
timestamp (str) – The date and time of the annotation, in ISO 8601 format (maps to the @timestamp body field).
service_version (str) – The version of the service.
service_environment (str | None) – The environment of the service.
message (str | None) – The message displayed in the annotation. Defaults to service.version server-side.
tags (list[str] | None) – Tags used by the Applications UI to distinguish APM annotations from other annotations. Defaults to ["apm"]; the apm tag cannot be removed.
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with the created annotation document (_id, _index and _source).

Raises:

BadRequestError – If the request body is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks annotation write privileges.
NotFoundError – If the annotation feature is unavailable.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> response = client.apm.create_annotation(
...     service_name="opbeans-java",
...     timestamp="2026-07-03T08:52:00.000Z",
...     service_version="1.2.3",
...     service_environment="production",
...     message="Deployed 1.2.3",
... )
>>> print(response.body["_source"]["annotation"]["type"])
deployment

search_annotations(*, service_name, environment=None, start=None, end=None, space_id=None, validate_spaces=None)[source]¶

Search for annotations.

Search for annotations related to a specific service.

Note

The 9.4.3 OpenAPI spec marks all three query parameters as optional, but the live server rejects requests that omit any of them (400 Bad Request). Pass environment="ENVIRONMENT_ALL" to search across all environments.

Parameters:

service_name (str) – The name of the service (URL path parameter).
environment (str | None) – The environment to filter annotations by. The sentinel values "ENVIRONMENT_ALL" and "ENVIRONMENT_NOT_DEFINED" are accepted. Required by the live server.
start (str | None) – The start date for the search, in ISO 8601 format (date-time). Required by the live server.
end (str | None) – The end date for the search, in ISO 8601 format (date-time). Required by the live server.
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an annotations list; each entry contains type, id, @timestamp and text.

Raises:

BadRequestError – If the query parameters are invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM read privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> response = client.apm.search_annotations(
...     service_name="opbeans-java",
...     environment="production",
...     start="2026-07-01T00:00:00.000Z",
...     end="2026-07-04T00:00:00.000Z",
... )
>>> for annotation in response.body["annotations"]:
...     print(annotation["text"])

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

Get a list of agent configurations.

Get all APM agent configurations stored in the .apm-agent-configuration index.

Parameters:

space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with a configurations list; each entry contains service, settings, @timestamp, applied_by_agent, etag and optionally agent_name.

Raises:

AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM read privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> response = client.apm.get_agent_configurations()
>>> for config in response.body["configurations"]:
...     print(config["service"], config["settings"])

create_or_update_agent_configuration(*, settings, service_name=None, service_environment=None, agent_name=None, overwrite=None, space_id=None, validate_spaces=None)[source]¶

Create or update agent configuration.

Create or update an APM agent configuration for a service. Omitting service_name/service_environment targets all services and/or all environments.

Parameters:

settings (dict[str, str]) – Agent configuration settings as string key/value pairs (e.g. {"transaction_sample_rate": "0.5"}).
service_name (str | None) – The name of the service the configuration applies to. Omit to target all services.
service_environment (str | None) – The environment of the service. Omit to target all environments.
agent_name (str | None) – The agent name, used by the UI to determine which settings to display.
overwrite (bool | None) – If True, an existing configuration for the same service/environment is overwritten.
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an empty body on success.

Raises:

BadRequestError – If the body is invalid (e.g. unknown setting).
AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM settings write privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> client.apm.create_or_update_agent_configuration(
...     service_name="opbeans-node",
...     service_environment="production",
...     settings={"transaction_sample_rate": "0.5"},
...     agent_name="nodejs",
...     overwrite=True,
... )

delete_agent_configuration(*, service_name=None, service_environment=None, space_id=None, validate_spaces=None)[source]¶

Delete agent configuration.

Delete the APM agent configuration that matches the given service name and environment.

Parameters:

service_name (str | None) – The name of the service the configuration applies to. Omit for an all-services configuration.
service_environment (str | None) – The environment of the service. Omit for an all-environments configuration.
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with the Elasticsearch delete result (e.g. result: "deleted").

Raises:

BadRequestError – If the body is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM settings write privileges.
NotFoundError – If no matching configuration exists.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> client.apm.delete_agent_configuration(
...     service_name="opbeans-node",
...     service_environment="production",
... )

get_agent_configuration(*, name=None, environment=None, space_id=None, validate_spaces=None)[source]¶

Get single agent configuration.

Get the single APM agent configuration matching the given service name and environment. Omitting name/environment returns the all-services/all-environments configuration if one exists.

Parameters:

name (str | None) – The service name of the configuration.
environment (str | None) – The service environment of the configuration.
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

id, service, settings, @timestamp, applied_by_agent, etag and optionally agent_name.

Return type:

ObjectApiResponse with the configuration document

Raises:

AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM read privileges.
NotFoundError – If no matching configuration exists.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Example

>>> response = client.apm.get_agent_configuration(
...     name="opbeans-node", environment="production"
... )
>>> print(response.body["settings"])
{'transaction_sample_rate': '0.5'}

search_agent_configurations(*, service_name=None, service_environment=None, etag=None, mark_as_applied_by_agent=None, error=None, space_id=None, validate_spaces=None)[source]¶

Look up a single agent configuration (APM Server search).

Deprecated since version 9.4: This endpoint is deprecated. It exists for APM Server / agents to poll configuration; use get_agent_configuration() to read a configuration interactively.

Search for a single agent configuration and update applied_by_agent: if the etag matches the stored one, applied_by_agent is set to true.

Parameters:

service_name (str | None) – The name of the service.
service_environment (str | None) – The environment of the service.
etag (str | None) – If the etag matches the stored configuration, applied_by_agent will be set to true.
mark_as_applied_by_agent (bool | None) – If True, forces applied_by_agent to true regardless of etag (needed for agents without etag support, e.g. Jaeger).
error (str | None) – If provided, the agent configuration is marked as errored and applied_by_agent is set to false.
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with the matching Elasticsearch hit (_id, _index and _source with the configuration).

Raises:

BadRequestError – If the body is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM read privileges.
NotFoundError – If no matching configuration exists.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> response = client.apm.search_agent_configurations(
...     service_name="opbeans-node",
...     service_environment="production",
...     etag="0bc3b5ebf18fba8163fe4c96f491e3767a358f85",
... )
>>> print(response.body["_source"]["settings"])

get_environments(*, service_name=None, space_id=None, validate_spaces=None)[source]¶

Get environments for service.

Get the list of environments for a service, used when creating an agent configuration. Environments already covered by a configuration are flagged with alreadyConfigured.

Parameters:

service_name (str | None) – The name of the service. Omit to list environments across all services.
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an environments list; each entry contains name (ALL_OPTION_VALUE represents “all environments”) and alreadyConfigured.

Raises:

AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM read privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> response = client.apm.get_environments(
...     service_name="opbeans-node"
... )
>>> for env in response.body["environments"]:
...     print(env["name"], env["alreadyConfigured"])

get_agent_name(*, service_name, space_id=None, validate_spaces=None)[source]¶

Get agent name for service.

Get the agent name for a service, derived from ingested APM data. Returns an empty object when the service has no APM data yet.

Parameters:

service_name (str) – The name of the service.
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an agentName field (e.g. nodejs) when APM data exists for the service; empty body otherwise.

Raises:

BadRequestError – If service_name is missing.
AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM read privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> response = client.apm.get_agent_name(
...     service_name="opbeans-node"
... )
>>> print(response.body.get("agentName"))
nodejs

get_sourcemaps(*, page=None, per_page=None, space_id=None, validate_spaces=None)[source]¶

Get source maps.

Get a list of the uploaded RUM source maps (stored as Fleet artifacts).

Parameters:

page (int | None) – Page number (1-based).
per_page (int | None) – Number of source maps per page (perPage query parameter).
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an artifacts list and a total count; each artifact contains id, identifier, body (with serviceName, serviceVersion, bundleFilepath and sourceMap), created and integrity metadata.

Raises:

AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM read privileges.
InternalServerError – If the Fleet artifacts store is unavailable.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> response = client.apm.get_sourcemaps(page=1, per_page=10)
>>> for artifact in response.body["artifacts"]:
...     print(artifact["identifier"])

upload_sourcemap(*, service_name, service_version, bundle_filepath, sourcemap, space_id=None, validate_spaces=None)[source]¶

Upload a source map.

Upload a RUM source map for a service so APM can un-minify RUM stack traces. The payload is sent as multipart/form-data. The maximum payload size accepted by Kibana is 1mb by default.

Parameters:

service_name (str) – The name of the service that the source map should apply to.
service_version (str) – The version of the service that the source map should apply to.
bundle_filepath (str) – The absolute path of the final bundle as used in the web application.
sourcemap (str | bytes | dict[str, Any]) – The source map content. It must follow the source map format specification. Accepts a dict (JSON encoded automatically), a JSON str, or raw bytes.
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

id, identifier, relative_url, body (compressed), created and integrity metadata.

Return type:

ObjectApiResponse with the created Fleet artifact

Raises:

BadRequestError – If the form fields or source map are invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM settings write privileges.
InternalServerError – If the Fleet artifacts store is unavailable.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Example

>>> response = client.apm.upload_sourcemap(
...     service_name="opbeans-rum",
...     service_version="1.2.3",
...     bundle_filepath="http://localhost/static/js/bundle.js",
...     sourcemap={
...         "version": 3,
...         "file": "bundle.js",
...         "sources": ["app.js"],
...         "names": [],
...         "mappings": "AAAA",
...     },
... )
>>> print(response.body["id"])

delete_sourcemap(*, id, space_id=None, validate_spaces=None)[source]¶

Delete source map.

Delete a previously uploaded source map by its artifact ID.

Parameters:

id (str) – The ID of the source map artifact to delete (as returned by get_sourcemaps() / upload_sourcemap(), e.g. "apm:opbeans-rum-1.2.3-<sha256>").
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an empty body on success.

Raises:

AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM settings write privileges.
InternalServerError – If the artifact cannot be deleted (e.g. unknown ID).
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> client.apm.delete_sourcemap(
...     id="apm:opbeans-rum-1.2.3-ba48e0ac0c14..."
... )

__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]

AsyncApmClient¶

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

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

Bases: AsyncNamespaceClient

Async client for the Kibana APM (Application Performance Monitoring) API.

Covers the Kibana 9.4.3 APM UI endpoints: APM agent keys, APM Server schema, service annotations, agent configurations, and RUM source maps.

Example

>>> from kibana import AsyncKibana
>>> client = AsyncKibana("http://localhost:5601", api_key="...")
>>>
>>> # Create an agent configuration
>>> await client.apm.create_or_update_agent_configuration(
...     service_name="opbeans-node",
...     service_environment="production",
...     settings={"transaction_sample_rate": "0.5"},
... )
>>>
>>> # List agent configurations
>>> configs = await client.apm.get_agent_configurations()
>>> for c in configs.body["configurations"]:
...     print(c["service"], c["settings"])

Usage

The AsyncApmClient provides the same methods as ApmClient 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:
        # Create an agent configuration (async)
        await client.apm.create_or_update_agent_configuration(
            service_name="opbeans-node",
            settings={"transaction_sample_rate": "0.5"},
        )

        # List configurations (async)
        configs = await client.apm.get_agent_configurations()

asyncio.run(main())

async create_agent_key(*, name, privileges, space_id=None, validate_spaces=None)[source]¶

Create an APM agent key.

Parameters:

name (str) – The name of the APM agent key.
privileges (list[str]) – The APM agent key privileges. One or more of "event:write" (required for ingesting APM agent events) and "config_agent:read" (required for APM agents to read agent configuration remotely).
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an agentKey object containing id, name, api_key and encoded (the base64 credentials).

Raises:

BadRequestError – If the request body is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks the required privileges to create APM agent keys.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> response = await client.apm.create_agent_key(
...     name="my-agent-key",
...     privileges=["event:write", "config_agent:read"],
... )
>>> print(response.body["agentKey"]["encoded"])

async save_server_schema(*, schema, space_id=None, validate_spaces=None)[source]¶

Save APM Server schema.

Deprecated since version 9.4: This endpoint is deprecated. It supports the APM Server to Fleet migration workflow in the Applications UI; manage the APM integration policy through Fleet instead.

Save the APM Server settings schema used when migrating a standalone APM Server to a Fleet-managed APM integration.

Parameters:

schema (dict[str, Any]) – Schema object with APM Server settings (arbitrary key/value pairs, e.g. {"apm-server.host": "0.0.0.0:8200"}).
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an empty body on success.

Raises:

BadRequestError – If the request body is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM settings write privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> await client.apm.save_server_schema(
...     schema={"apm-server.host": "0.0.0.0:8200"}
... )

async create_annotation(*, service_name, timestamp, service_version, service_environment=None, message=None, tags=None, space_id=None, validate_spaces=None)[source]¶

Create a service annotation.

Create a new annotation (e.g. a deployment marker) for a specific service. Annotations are stored in the observability-annotations index and rendered in the Applications UI charts.

Parameters:

service_name (str) – The name of the service (URL path parameter).
timestamp (str) – The date and time of the annotation, in ISO 8601 format (maps to the @timestamp body field).
service_version (str) – The version of the service.
service_environment (str | None) – The environment of the service.
message (str | None) – The message displayed in the annotation. Defaults to service.version server-side.
tags (list[str] | None) – Tags used by the Applications UI to distinguish APM annotations from other annotations. Defaults to ["apm"]; the apm tag cannot be removed.
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with the created annotation document (_id, _index and _source).

Raises:

BadRequestError – If the request body is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks annotation write privileges.
NotFoundError – If the annotation feature is unavailable.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> response = await client.apm.create_annotation(
...     service_name="opbeans-java",
...     timestamp="2026-07-03T08:52:00.000Z",
...     service_version="1.2.3",
...     service_environment="production",
...     message="Deployed 1.2.3",
... )
>>> print(response.body["_source"]["annotation"]["type"])
deployment

async search_annotations(*, service_name, environment=None, start=None, end=None, space_id=None, validate_spaces=None)[source]¶

Search for annotations.

Search for annotations related to a specific service.

Note

Parameters:

service_name (str) – The name of the service (URL path parameter).
environment (str | None) – The environment to filter annotations by. The sentinel values "ENVIRONMENT_ALL" and "ENVIRONMENT_NOT_DEFINED" are accepted. Required by the live server.
start (str | None) – The start date for the search, in ISO 8601 format (date-time). Required by the live server.
end (str | None) – The end date for the search, in ISO 8601 format (date-time). Required by the live server.
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an annotations list; each entry contains type, id, @timestamp and text.

Raises:

BadRequestError – If the query parameters are invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM read privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> response = await client.apm.search_annotations(
...     service_name="opbeans-java",
...     environment="production",
...     start="2026-07-01T00:00:00.000Z",
...     end="2026-07-04T00:00:00.000Z",
... )
>>> for annotation in response.body["annotations"]:
...     print(annotation["text"])

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

Get a list of agent configurations.

Get all APM agent configurations stored in the .apm-agent-configuration index.

Parameters:

space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with a configurations list; each entry contains service, settings, @timestamp, applied_by_agent, etag and optionally agent_name.

Raises:

AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM read privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> response = await client.apm.get_agent_configurations()
>>> for config in response.body["configurations"]:
...     print(config["service"], config["settings"])

async create_or_update_agent_configuration(*, settings, service_name=None, service_environment=None, agent_name=None, overwrite=None, space_id=None, validate_spaces=None)[source]¶

Create or update agent configuration.

Create or update an APM agent configuration for a service. Omitting service_name/service_environment targets all services and/or all environments.

Parameters:

settings (dict[str, str]) – Agent configuration settings as string key/value pairs (e.g. {"transaction_sample_rate": "0.5"}).
service_name (str | None) – The name of the service the configuration applies to. Omit to target all services.
service_environment (str | None) – The environment of the service. Omit to target all environments.
agent_name (str | None) – The agent name, used by the UI to determine which settings to display.
overwrite (bool | None) – If True, an existing configuration for the same service/environment is overwritten.
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an empty body on success.

Raises:

BadRequestError – If the body is invalid (e.g. unknown setting).
AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM settings write privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> await client.apm.create_or_update_agent_configuration(
...     service_name="opbeans-node",
...     service_environment="production",
...     settings={"transaction_sample_rate": "0.5"},
...     agent_name="nodejs",
...     overwrite=True,
... )

async delete_agent_configuration(*, service_name=None, service_environment=None, space_id=None, validate_spaces=None)[source]¶

Delete agent configuration.

Delete the APM agent configuration that matches the given service name and environment.

Parameters:

service_name (str | None) – The name of the service the configuration applies to. Omit for an all-services configuration.
service_environment (str | None) – The environment of the service. Omit for an all-environments configuration.
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with the Elasticsearch delete result (e.g. result: "deleted").

Raises:

BadRequestError – If the body is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM settings write privileges.
NotFoundError – If no matching configuration exists.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> await client.apm.delete_agent_configuration(
...     service_name="opbeans-node",
...     service_environment="production",
... )

async get_agent_configuration(*, name=None, environment=None, space_id=None, validate_spaces=None)[source]¶

Get single agent configuration.

Get the single APM agent configuration matching the given service name and environment. Omitting name/environment returns the all-services/all-environments configuration if one exists.

Parameters:

name (str | None) – The service name of the configuration.
environment (str | None) – The service environment of the configuration.
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

id, service, settings, @timestamp, applied_by_agent, etag and optionally agent_name.

Return type:

ObjectApiResponse with the configuration document

Raises:

AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM read privileges.
NotFoundError – If no matching configuration exists.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Example

>>> response = await client.apm.get_agent_configuration(
...     name="opbeans-node", environment="production"
... )
>>> print(response.body["settings"])
{'transaction_sample_rate': '0.5'}

async search_agent_configurations(*, service_name=None, service_environment=None, etag=None, mark_as_applied_by_agent=None, error=None, space_id=None, validate_spaces=None)[source]¶

Look up a single agent configuration (APM Server search).

Deprecated since version 9.4: This endpoint is deprecated. It exists for APM Server / agents to poll configuration; use get_agent_configuration() to read a configuration interactively.

Search for a single agent configuration and update applied_by_agent: if the etag matches the stored one, applied_by_agent is set to true.

Parameters:

service_name (str | None) – The name of the service.
service_environment (str | None) – The environment of the service.
etag (str | None) – If the etag matches the stored configuration, applied_by_agent will be set to true.
mark_as_applied_by_agent (bool | None) – If True, forces applied_by_agent to true regardless of etag (needed for agents without etag support, e.g. Jaeger).
error (str | None) – If provided, the agent configuration is marked as errored and applied_by_agent is set to false.
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with the matching Elasticsearch hit (_id, _index and _source with the configuration).

Raises:

BadRequestError – If the body is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM read privileges.
NotFoundError – If no matching configuration exists.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> response = await client.apm.search_agent_configurations(
...     service_name="opbeans-node",
...     service_environment="production",
...     etag="0bc3b5ebf18fba8163fe4c96f491e3767a358f85",
... )
>>> print(response.body["_source"]["settings"])

async get_environments(*, service_name=None, space_id=None, validate_spaces=None)[source]¶

Get environments for service.

Get the list of environments for a service, used when creating an agent configuration. Environments already covered by a configuration are flagged with alreadyConfigured.

Parameters:

service_name (str | None) – The name of the service. Omit to list environments across all services.
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an environments list; each entry contains name (ALL_OPTION_VALUE represents “all environments”) and alreadyConfigured.

Raises:

AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM read privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> response = await client.apm.get_environments(
...     service_name="opbeans-node"
... )
>>> for env in response.body["environments"]:
...     print(env["name"], env["alreadyConfigured"])

async get_agent_name(*, service_name, space_id=None, validate_spaces=None)[source]¶

Get agent name for service.

Get the agent name for a service, derived from ingested APM data. Returns an empty object when the service has no APM data yet.

Parameters:

service_name (str) – The name of the service.
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an agentName field (e.g. nodejs) when APM data exists for the service; empty body otherwise.

Raises:

BadRequestError – If service_name is missing.
AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM read privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> response = await client.apm.get_agent_name(
...     service_name="opbeans-node"
... )
>>> print(response.body.get("agentName"))
nodejs

async get_sourcemaps(*, page=None, per_page=None, space_id=None, validate_spaces=None)[source]¶

Get source maps.

Get a list of the uploaded RUM source maps (stored as Fleet artifacts).

Parameters:

page (int | None) – Page number (1-based).
per_page (int | None) – Number of source maps per page (perPage query parameter).
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

Raises:

AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM read privileges.
InternalServerError – If the Fleet artifacts store is unavailable.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> response = await client.apm.get_sourcemaps(page=1, per_page=10)
>>> for artifact in response.body["artifacts"]:
...     print(artifact["identifier"])

async upload_sourcemap(*, service_name, service_version, bundle_filepath, sourcemap, space_id=None, validate_spaces=None)[source]¶

Upload a source map.

Upload a RUM source map for a service so APM can un-minify RUM stack traces. The payload is sent as multipart/form-data. The maximum payload size accepted by Kibana is 1mb by default.

Parameters:

service_name (str) – The name of the service that the source map should apply to.
service_version (str) – The version of the service that the source map should apply to.
bundle_filepath (str) – The absolute path of the final bundle as used in the web application.
sourcemap (str | bytes | dict[str, Any]) –
The source map content. It must follow the source map format specification. Accepts a dict (JSON encoded automatically), a JSON str, or raw bytes.
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

id, identifier, relative_url, body (compressed), created and integrity metadata.

Return type:

ObjectApiResponse with the created Fleet artifact

Raises:

BadRequestError – If the form fields or source map are invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM settings write privileges.
InternalServerError – If the Fleet artifacts store is unavailable.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Example

>>> response = await client.apm.upload_sourcemap(
...     service_name="opbeans-rum",
...     service_version="1.2.3",
...     bundle_filepath="http://localhost/static/js/bundle.js",
...     sourcemap={
...         "version": 3,
...         "file": "bundle.js",
...         "sources": ["app.js"],
...         "names": [],
...         "mappings": "AAAA",
...     },
... )
>>> print(response.body["id"])

async delete_sourcemap(*, id, space_id=None, validate_spaces=None)[source]¶

Delete source map.

Delete a previously uploaded source map by its artifact ID.

Parameters:

id (str) – The ID of the source map artifact to delete (as returned by get_sourcemaps() / upload_sourcemap(), e.g. "apm:opbeans-rum-1.2.3-<sha256>").
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an empty body on success.

Raises:

AuthenticationException – If authentication fails.
AuthorizationException – If the user lacks APM settings write privileges.
InternalServerError – If the artifact cannot be deleted (e.g. unknown ID).
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> await client.apm.delete_sourcemap(
...     id="apm:opbeans-rum-1.2.3-ba48e0ac0c14..."
... )

__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]