Main API Classes

The pyc8y module's main API classes provide access to various contexts within the Cumulocity REST API. Use it to read existing data or modify in bulk.

See also the Object model section for object creation and object-oriented access in general.

Querying the database

The main API classes can be used to read individual objects by their respective key, usually the Cumulocity object ID:

some_object = await c8y.inventory.get("123456")
some_user = await c8y.users.get("mini_me")
some_id = await c8y.identity.get("9876543210", "c8y_Serial")

To access entire collections most APIs provide convenient query functions which reflect the respective API's capabilities:

objects = await c8y.inventory.get_all(name="My*", limit=10)

The get_all function provides the query results as a list, the feature-equivalent select function works as a generator for streaming access. Both functions perform automatic paging if necessary.

The returned objects are instances of the Object model and the functions are properly typed, so the results can conveniently used directly as-is:

async for event in c8y.events.select(source="123456", max_age="1d", limit=100):
    print(f"Event: #{event.id} {event.time}, Type {event.type}")

Flexible query parameters

While all query functions are functionally equivalent, each API provides a specialized version which reflects the respective REST API's capabilities. For example, the Inventory API provides OData-like queries which for example are not supported for the Event API or Operation API.

objects = await c8y.inventory.get_all(query="name eq 'My*'", limit=10)

All potential filters available through code completion. They match the REST API's naming and function - however, the names have been renamed to match Python's snake_case naming convention (e.g. date_from instead of dateFrom). The original names can always be used as a fallback, though. Additionally, convenient alternatives are provided for date-like query parameters:

c8y.events.get_all(source="123456", dateFrom="2025-01-01")  # original
c8y.events.get_all(source="123456", date_from="2025-01-01")  # Pythonic
c8y.events.get_all(source="123456", after="2025-01-01")  # alternative
c8y.events.get_all(source="123456", max_age="1d")  # convenience helper

All date-like parameters accept timezone-aware datetime objects, ISO date/time strings as well as "now" as a convenience alternative.

As a fallback, all query functions support the direct definition of a REST API expression:

# knowing it better
c8y.inventory.get_all("q=$filter=name eq 'M01' $orderby=lastUpdated")

High-performance throughput

The SDK features an async first design with IO concurrency and high throughput in mind. Hence, all query functions can be executed in concurrent mode via the workers parameter:

all_devices = await c8y.device_inventory.get_all(limit=None, page_size=100, workers=20)

This will internally fetch pages concurrently and return the complete set. Results will be returned in random order (by completion), unless an ordering parameter is specified:

all_events = await c8y.events.get_all(
    source="12345",
    ascending=True,  # or: revert=True
    limit=None,
    page_size=100,
    workers=20)

Especially when working on large data sets, the full result object's JSON is usually obsolete. To directly forfeit the JSON data and only process relevant fields, the as_values parameter can be used on all query functions:

async for values in c8y.inventory.select(
        type="MyDevice",
        as_values=("id", ("name", "undefined"), "lastUpdated")):
    print(f"#{values[0]} '{values[1]}', last updated: {values[2]}")

Object manipulation and bulk processing

The main API classes can also be used to directly manipulate the database without the need to pull object instances:

# add a new fragment to a known set of inventory objects:
new_fragment_json = {"my_AdditionalFragment": {"essential": True}}
await c8y.inventory.update(new_fragment_json, "123456", "1238957", "12399192")

Similar functions exist to create and delete objects in bulk. Each API class additionally provides access to API specific functionality, for example to assign group memberships, define child devices, reset user passwords, ...

Like the query functions, all bulk operations feature a workers parameter to enable concurrency and maximize throughput:

many_ids = [...]
await c8y.inventory.delete(*many_ids, workers=20)

Because all these functions are defined as async, the bulk operations can easily be combined using standard asyncio means:

# clean up my data
object_events = await c8y.events.get_all(source=my_object.id, limit=None, workers=20, as_values="id")
object_alarms = await c8y.alarms.get_all(source=my_object.id, limit=None, workers=20, as_values="id")
await asyncio.gather(
    c8y.events.delete( *object_events, workers=20),
    c8y.alarms.delete(*object_alarms, workers=20),
)
await c8y.inventory.delete(my_object.id)

`Inventory`

`apply_to(model: dict | MO, *objects: str | MO, workers: int | None = None) -> None` `async`

`create(*objects: MO, workers: int | None = None) -> None` `async`

`delete(*objects: str | MO, workers: int | None = None) -> None` `async`

`get(id: str, *, with_children: bool | None = None, with_children_count: bool | None = None, skip_children_names: bool | None = None, with_parents: bool | None = None, with_latest_values: bool | None = None, **kwargs) -> MO` `async`

Retrieve a specific object from the database.

Parameters:

Name	Type	Description	Default
`id`	`str`	Cumulocity ID of the object	required
`with_children`	`bool`	Whether children with ID and name should be included with each returned object	`None`
`with_children_count`	`bool`	When set to true, the returned result will contain the total number of children in the respective child additions, assets and devices sub fragments.	`None`
`skip_children_names`	`bool`	If true, returned references of child devices won't contain their names.	`None`
`with_parents`	`bool`	Whether to include a device's parents.	`None`
`with_latest_values`	`bool`	If true the platform includes the fragment `c8y_LatestMeasurements, which contains the latest measurement values reported by the device to the platform.	`None`

Returns:

Type	Description
`MO`	The referenced object.

Raises:

Type	Description
`KeyError`	if the ID is not defined within the database.

get_all(expression: str | None = None, *, query: str | None = None, ids: Sequence[str] | None = None, order_by: str | None = None, type: str | None = None, parent: str | None = None, fragment: str | None = None, fragments: str | Sequence[str] | None = None, name: str | None = None, owner: str | None = None, text: str | None = None, only_roots: bool | None = None, with_children: bool | None = None, with_children_count: bool | None = None, skip_children_names: bool | None = None, with_groups: bool | None = None, with_parents: bool | None = None, with_latest_values: bool | None = None, limit: int | None = 5, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None, **kwargs) -> list[MO] `async`

Query the database for objects and return the results as list.

This function is a greedy version of the select function. All available results are read immediately and returned as list.

Returns:

Type	Description
`list[MO]`	List of object instances or values/value tuples if the `as_values` parameter is defined,

get_by(expression: str | None = None, *, query: str | None = None, ids: Sequence[str] | None = None, order_by: str | None = None, type: str | None = None, parent: str | None = None, fragment: str | None = None, fragments: str | Sequence[str] | None = None, name: str | None = None, owner: str | None = None, text: str | None = None, only_roots: bool | None = None, with_children: bool | None = None, with_children_count: bool | None = None, skip_children_names: bool | None = None, with_groups: bool | None = None, with_parents: bool | None = None, with_latest_values: bool | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, **kwargs) -> MO `async`

Query the database for a specific object.

This function is a special version of the select function assuming a single result being returned by the query.

Returns:

Type	Description
`MO`	The specified object.

Raises:

Type	Description
`ValueError`	if the query did not return any or more than one result.

`get_count(expression: str | None = None, *, query: str | None = None, ids: Sequence[str] | None = None, type: str | None = None, parent: str | None = None, fragment: str | None = None, fragments: str | Sequence[str] | None = None, name: str | None = None, owner: str | None = None, text: str | None = None, **kwargs) -> int` `async`

Calculate the number of potential results of a database query.

This function uses the same parameters as the select function.

Returns:

Type	Description
`int`	Number of potential results.

`get_latest_availability(mo_id: str) -> Availability` `async`

Retrieve the latest availability information of a managed object.

Parameters:

Name	Type	Description	Default
`mo_id`	`str`	Device (managed object) ID	required

Return

DeviceAvailability object

`get_supported_measurements(mo_id: str) -> list[str]` `async`

Retrieve all supported measurements names of a specific managed object.

Parameters:

Name	Type	Description	Default
`mo_id`	`str`	Managed object ID	required

Return

List of measurement fragment names.

`get_supported_series(mo_id: str) -> list[str]` `async`

Retrieve all supported measurement series names of a specific managed object.

Parameters:

Name	Type	Description	Default
`mo_id`	`str`	Managed object ID	required

Return

List of series names.

select(expression: str | None = None, *, query: str | None = None, ids: Sequence[str] | None = None, order_by: str | None = None, type: str | None = None, parent: str | None = None, fragment: str | None = None, fragments: str | Sequence[str] | None = None, name: str | None = None, owner: str | None = None, text: str | None = None, only_roots: bool | None = None, with_children: bool | None = None, with_children_count: bool | None = None, skip_children_names: bool | None = None, with_groups: bool | None = None, with_parents: bool | None = None, with_latest_values: bool | None = None, limit: int | None = 5, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None, **kwargs) -> AsyncIterator[MO]

Query the database for objects and iterate over the results.

This function is implemented in a lazy fashion - results will only be fetched from the database as long there is a consumer for them.

Most parameters are considered to be filters, limiting the result set to objects which meet the filters specification. Filters can be combined (within reason).

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`query`	`str`	Custom Cumulocity query string; if specified, all other filter parameters are ignored.	`None`
`ids`	`Sequence[str]`	Sequence of database IDs to retrieve; if specified, all other filter parameters are ignored.	`None`
`order_by`	`str`	Server-side ordering expression (e.g. `name asc`).	`None`
`type`	`str`	Object type to filter by.	`None`
`parent`	`str`	Database ID of a parent group/device; restricts results to direct children of this parent.	`None`
`fragment`	`str`	Name of a present custom/standard fragment.	`None`
`fragments`	`str \| Sequence[str]`	Name or names of fragments; objects must have all listed fragments present. A single fragment name may be passed as a bare string.	`None`
`name`	`str`	Exact name to filter by.	`None`
`owner`	`str`	Username of the object's owner.	`None`
`text`	`str`	Full-text search match.	`None`
`only_roots`	`bool`	If true, only return objects without parents (root nodes of the inventory hierarchy).	`None`
`with_children`	`bool`	Whether children with ID and name should be included with each returned object.	`None`
`with_children_count`	`bool`	When set to true, the returned result will contain the total number of children in the respective child additions, assets and devices sub fragments.	`None`
`skip_children_names`	`bool`	If true, returned references of child devices won't contain their names.	`None`
`with_groups`	`bool`	Whether to include parent groups (asset parents) of each returned object.	`None`
`with_parents`	`bool`	Whether to include a device's parents.	`None`
`with_latest_values`	`bool`	If true the platform includes the fragment `c8y_LatestMeasurements, which contains the latest measurement values reported by the device to the platform.	`None`
`limit`	`int \| None`	Maximum number of results. Default is 5 to support quick Jupyter-style exploration; pass `None` to fetch all matching.	`5`
`include`	`str \| JsonMatcher`	Matcher/expression to filter the query results (on client side). The inclusion is applied first. Creates a PyDF (Python Display Filter) matcher by default for strings.	`None`
`exclude`	`str \| JsonMatcher`	Matcher/expression to filter the query results (on client side). The exclusion is applied second. Creates a PyDF (Python Display Filter) matcher by default for strings.	`None`
`page_size`	`int \| None`	Number of records read per request. If None (default), inferred from `limit` and whether client-side filters are set.	`None`
`page_number`	`int`	Pull a specific page; this effectively disables automatic follow-up page retrieval.	`None`
`as_values`	`str \| tuple \| Sequence[str \| tuple] \| None`	(*str\|tuple): Don't parse objects, but directly extract the values at certain JSON paths as tuples; If the path is not defined in a result, None is used; Specify a tuple to define a proper default value for each path.	`None`
`workers`	`int`	Number of parallel page-fetch workers; if None, pages are fetched sequentially.	`None`

Returns:

Type	Description
`AsyncIterator[MO]`	Async iterator for object instances or values/value tuples if the
`AsyncIterator[MO]`	`as_values` parameter is defined.

`update(*objects: MO, workers: int | None = None) -> None` `async`

`DeviceInventory`

Provides access to the Device Inventory API.

This class can be used for get, search for, create, update and delete device objects within the Cumulocity database.

See also: https://cumulocity.com/api/#tag/Inventory-API

`accept(id: str)` `async`

Accept a device request.

Parameters:

Name	Type	Description	Default
`id`	`str`	Unique ID of the device (e.g. Serial, IMEI); this is	required

`delete(*devices: str | Device, workers: int | None = None) -> None` `async`

Delete one or more devices and the corresponding within the database.

The objects can be specified as instances of a database object (then, the id field needs to be defined) or simply as ID (integers or strings).

Note: In contrast to the regular delete function defined in class ManagedObject, this version also removes the corresponding device user from database by invoking the delete function on the Device object which does this by default.

Parameters:

Name	Type	Description	Default
`*devices`	`str \| Device`	Objects (or their database ID). workers (int): Number of workers to use for parallel processing or None to process sequentially.	`()`

`request(id: str)` `async`

Create a device request.

Parameters:

Name	Type	Description	Default
`id`	`str`	Unique ID of the device (e.g. Serial, IMEI); this is	required

`Identity`

Provides access to the Identity API.

The Identity API uses non-standard resource paths and does not follow the standard CumulocityResource pagination pattern.

https://cumulocity.com/api/core/#tag/External-IDs

https://cumulocity.com/api/core/#tag/Identity-API

`init(c8y: CumulocityRestClient)`

`create(*objects: ExternalId, workers: int | None = None, external_id: str | None = None, external_type: str | None = None, managed_object_id: str | None = None) -> None` `async`

Create ExternalID objects within the database.

A single ExternalID object can be created by specifying parameters external_id, external_type, and managed_object_id directly. Alternatively, a collection of ExternalID objects can be created in a single call, optionally specifying the number of parallel worker threads.

Parameters:

Name	Type	Description	Default
`*objects`	`ExternalID`	Collection of ExternalID instances	`()`
`workers`	`int`	The number of parallel processes to use	`None`
`external_id`	`str`	A string to be used as ID for external use	`None`
`external_type`	`str`	Type of the external ID	`None`
`managed_object_id`	`str`	Valid database ID of a managed object	`None`

`delete(*objects: ExternalId, workers: int | None = None, external_id: str | None = None, external_type: str | None = None) -> None` `async`

Remove an External ID from the database.

A single ExternalID object can be deleted by specifying parameters external_id and external_type directly. Alternatively, a collection of ExternalID objects can be deleted in a single call, optionally specifying the number of parallel worker threads.

Parameters:

Name	Type	Description	Default
`*objects`	`ExternalID`	Collection of ExternalID instances	`()`
`workers`	`int`	The number of parallel processes to use	`None`
`external_id`	`str`	A string to be used as ID for external use	`None`
`external_type`	`str`	Type of the external ID	`None`

`get(external_id: str, external_type: str) -> ExternalId` `async`

Obtain a specific External ID from the database.

Parameters:

Name	Type	Description	Default
`external_id`	`str`	A string to be used as ID for external use	required
`external_type`	`str`	Type of the external ID	required

Returns:

Type	Description
`ExternalId`	ExternalId object

`get_all(object_id: str) -> list[ExternalId]` `async`

Read all external IDs for a managed object.

Parameters:

Name	Type	Description	Default
`object_id`	`str`	Valid database ID of a managed object	required

Returns:

Type	Description
`list[ExternalId]`	A list of ExternalId instances (can be empty)

`get_id(external_id: str, external_type: str) -> str` `async`

Read the ID of the referenced managed object by its external ID.

Parameters:

Name	Type	Description	Default
`external_id`	`str`	A string to be used as ID for external use	required
`external_type`	`str`	Type of the external ID	required

Returns:

Type	Description
`str`	A database ID (string)

`get_object(external_id: str, external_type: str)` `async`

Read a managed object by its external ID reference.

Parameters:

Name	Type	Description	Default
`external_id`	`str`	A string to be used as ID for external use	required
`external_type`	`str`	Type of the external ID	required

Returns:

Type	Description
	ManagedObject instance

`Binaries`

Provides access to the Binaries API.

See also: https://cumulocity.com/api/core/#tag/Binaries

`create(*binaries: Binary, workers: int | None = None) -> int` `async`

Create binaries, i.e. upload files.

Each of the binaries must have a file attribute set.

Parameters:

Name	Type	Description	Default
`*binaries`	`Binary`	Binaries to upload	`()`
`workers`	`int`	Number of parallel workers	`None`

Returns:

Type	Description
`int`	The number of created binaries

Raises:

Type	Description
`FileNotFoundError`	if one of the file attributes refers to an invalid path

`delete(*objects: str | Binary, workers: int | None = None) -> None` `async`

get_all(expression: str | None = None, *, ids: Sequence[str] | None = None, type: str | None = None, owner: str | None = None, child_device: str | None = None, child_asset: str | None = None, child_addition: str | None = None, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, limit: int | None = 5, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None, **kwargs) -> list[Binary] `async`

Query the database for binary objects and return the results as list.

See select for a documentation of arguments.

Returns:

Type	Description
`list[Binary]`	List of Binary instances

`get_count(expression: str | None = None, *, ids: Sequence[str] | None = None, type: str | None = None, owner: str | None = None, child_device: str | None = None, child_asset: str | None = None, child_addition: str | None = None, **kwargs) -> int` `async`

Calculate the number of potential results of a database query.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`

Returns:

Type	Description
`int`	Number of potential results

`read_file(id: str) -> bytes` `async`

Read the binary content of a specific binary.

Parameters:

Name	Type	Description	Default
`id`	`str`	The database ID of the binary object	required

Returns:

Type	Description
`bytes`	The binary attachment's content as bytes

select(expression: str | None = None, *, ids: Sequence[str] | None = None, type: str | None = None, owner: str | None = None, child_device: str | None = None, child_asset: str | None = None, child_addition: str | None = None, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, limit: int | None = 5, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None, **kwargs) -> AsyncIterator[Binary]

Query the database for binaries and iterate over the results.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`ids`	`list`	Specific object IDs to select	`None`
`type`	`str`	Object type filter	`None`
`owner`	`str`	Username of the object owner	`None`
`child_device`	`str`	Object ID of a child device	`None`
`child_asset`	`str`	Object ID of a child asset	`None`
`child_addition`	`str`	Object ID of a child addition	`None`
`include`	`str \| JsonMatcher`	Client-side inclusion filter	`None`
`exclude`	`str \| JsonMatcher`	Client-side exclusion filter	`None`
`limit`	`int \| None`	Maximum number of results. Default is 5 to support quick Jupyter-style exploration; pass `None` to fetch all matching.	`5`
`page_size`	`int \| None`	Number of records read per request. If None (default), inferred from `limit` and whether client-side filters are set.	`None`
`page_number`	`int`	Pull a specific page only	`None`
`as_values`	`str \| tuple \| Sequence[str \| tuple] \| None`	Extract values at JSON paths as tuples	`None`
`workers`	`int`	Number of parallel page-fetch workers	`None`

Returns:

Type	Description
`AsyncIterator[Binary]`	AsyncIterator of Binary instances

`update(id: str, file: FileSpec, type: str | None = None) -> None` `async`

Update a binary attachment.

Parameters:

Name	Type	Description	Default
`id`	`str`	ID of an existing Binary within Cumulocity	required
`file`	`str \| file - like`	File to upload	required
`type`	`str`	Content type of the file	`None`

`upload(file: FileSpec, name: str, type: str) -> Binary` `async`

Upload a file.

Parameters:

Name	Type	Description	Default
`file`	`str \| file - like`	File to upload	required
`name`	`str`	Virtual name of the file	required
`type`	`str`	MIME type of the file	required

Returns:

Type	Description
`Binary`	A Binary instance referencing the uploaded file

Raises:

Type	Description
`FileNotFoundError`	if the file refers to an invalid path

`Measurements`

`collect_series(expression: str | None = None, *, source: str | None = None, aggregation: str | None = None, series: str | Sequence[str] | None = None, before: str | datetime | None = None, after: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, asc: bool | None = None, revert: bool | None = None, value: str | Sequence[str] | None = None, timestamps: bool | str | None = None, **kwargs)` `async`

Query the database for series values.

This function is functionally the same as using the get_series function with an immediate collect on the result.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`source`	`str`	Database ID of a source device	`None`
`aggregation`	`str`	Aggregation type	`None`
`series`	`str \| Sequence[str]`	Series' to query and collect; If multiple series are collected each element in the result will be a tuple. If omitted, all available series are collected.	`None`
`before`	`datetime \| str`	Datetime object or ISO date/time string. Only measurements assigned to a time before this date are included.	`None`
`after`	`datetime \| str`	Datetime object or ISO date/time string. Only measurements assigned to a time after this date are included.	`None`
`min_age`	`timedelta`	Timedelta object. Only measurements of at least this age are included.	`None`
`max_age`	`timedelta`	Timedelta object. Only measurements with at most this age are included.	`None`
`asc`	`bool`	Return results in ascending (oldest first) order if True, descending (newest first) if False. None uses the server default (ascending for Measurements).	`None`
`revert`	`bool`	The c8y-native server param. `True` flips the default order to descending. If both `asc` and `revert` are supplied, `revert` wins.	`None`
`value`	`str`	Which value (min/max) to collect. If omitted, both values will be collected, grouped as 2-tuples.	`None`
`timestamps`	`bool \| str`	Whether each element in the result list will be prepended with the corresponding timestamp. If True, the timestamp string will be included; Use 'datetime' or 'epoch' to parse the timestamp string.	`None`

Returns:

Type	Description
	A simple list or list of tuples (potentially nested) depending on the
	parameter combination.

See also: https://cumulocity.com/api/core/#operation/getMeasurementSeriesResource

`create(*objects: Measurement, workers: int | None = None) -> None` `async`

`delete(*objects: str | Measurement, workers: int | None = None) -> None` `async`

`delete_by(expression: str | None = None, *, type: str | None = None, source: str | None = None, value_fragment_type: str | None = None, value_fragment_series: str | None = None, series: str | None = None, fragment: str | None = None, date_from: str | datetime | None = None, date_to: str | datetime | None = None, before: str | datetime | None = None, after: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, **kwargs)` `async`

Query the database and delete matching measurements.

All parameters are considered to be filters, limiting the result set to objects which meet the filters specification. Filters can be combined (within reason).

Note: In Cumulocity, measurements are deleted asynchronously by design.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`type`	`str`	Alarm type	`None`
`source`	`str`	Database ID of a source device	`None`
`value_fragment_type`	`str`	The series' value fragment name (e.g. c8y_Environment)	`None`
`value_fragment_series`	`str`	The series' name (within the value fragment, e.g. Temperature)	`None`
`series`	`str`	Full name of a present series within a value fragment e.g. "c8y_Environment.Temperature"	`None`
`fragment`	`str`	Name of a present custom/standard fragment	`None`
`before`	`datetime \| str`	Datetime object or ISO date/time string. Only measurements assigned to a time before this date are returned.	`None`
`after`	`datetime \| str`	Datetime object or ISO date/time string. Only measurements assigned to a time after this date are returned.	`None`
`date_from`	`str \| datetime`	Same as `after`	`None`
`date_to`	`str \| datetime`	Same as `before`	`None`
`min_age`	`timedelta`	Timedelta object. Only measurements of at least this age are returned.	`None`
`max_age`	`timedelta`	Timedelta object. Only measurements with at most this age are returned.	`None`

`get(id: str) -> Measurement` `async`

Get a Measurement by ID.

get_all(expression: str | None = None, *, type: str | None = None, source: str | None = None, value_fragment_type: str | None = None, value_fragment_series: str | None = None, series: str | None = None, before: str | datetime | None = None, after: str | datetime | None = None, date_from: str | datetime | None = None, date_to: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, asc: bool | None = None, revert: bool | None = None, limit: int | None = 5, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None, **kwargs) -> list[Measurement] `async`

Query the database for measurements and return the results as list.

This function is a greedy version of the select function. All available results are read immediately and returned as list.

Returns:

Type	Description
`list[Measurement]`	List of matching Measurement objects or values/value tuples if the `as_values` parameter is defined.

`get_count(expression: str | None = None, *, type: str | None = None, source: str | None = None, value_fragment_type: str | None = None, value_fragment_series: str | None = None, series: str | None = None, before: str | datetime | None = None, after: str | datetime | None = None, date_from: str | datetime | None = None, date_to: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, **kwargs) -> int` `async`

Calculate the number of potential results of a database query.

This function uses the same parameters as the select function.

Returns:

Type	Description
`int`	Number of potential results

`get_last(expression: str | None = None, *, type: str | None = None, source: str | None = None, value_fragment_type: str | None = None, value_fragment_series: str | None = None, series: str | None = None, date_to: str | datetime | None = None, before: str | datetime | None = None, min_age: str | timedelta | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, **kwargs) -> Measurement | None` `async`

Query the database and return the last matching measurement.

This function is a special variant of the select function. Only the last matching result is returned.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`type`	`str`	Alarm type	`None`
`source`	`str`	Database ID of a source device	`None`
`value_fragment_type`	`str`	The series' value fragment name (e.g. c8y_Environment)	`None`
`value_fragment_series`	`str`	The series' name (within the value fragment, e.g. Temperature)	`None`
`series`	`str`	Full name of a present series within a value fragment e.g. "c8y_Environment.Temperature"	`None`
`before`	`datetime \| str`	Datetime object or ISO date/time string. Only measurements assigned to a time before this date are returned.	`None`
`date_to`	`str \| datetime`	Same as `before`	`None`
`min_age`	`timedelta`	Timedelta object. Only measurements of at least this age are returned.	`None`
`as_values`	`str \| tuple \| Sequence[str \| tuple] \| None`	(*str\|tuple): Don't parse object, but directly extract the values at certain JSON paths as tuples; If the path is not defined in a result, None is used; Specify a tuple to define a proper default value for each path.	`None`

Returns: Last matching Measurement object or values/value tuples if the as_values parameter is defined.

`get_series(expression: str | None = None, *, source: str | None = None, aggregation: str | None = None, aggregation_function: str | Sequence[str] | None = None, aggregation_interval: str | None = None, series: str | Sequence[str] | None = None, before: str | datetime | None = None, after: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, asc: bool | None = None, revert: bool | None = None, **kwargs) -> Series` `async`

Query the database for a list of series and their values.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`source`	`str`	Database ID of a source device	`None`
`aggregation`	`str`	Aggregation type	`None`
`aggregation_function`	`str`	Aggregation function, e.g. "min", "max", "avg", "sum", "count". Needs aggregation_interval.	`None`
`aggregation_interval`	`str`	Aggregation interval for the aggregation function.	`None`
`series`	`str \| Sequence[str]`	Series' to query	`None`
`before`	`datetime \| str`	Datetime object or ISO date/time string. Only measurements assigned to a time before this date are included.	`None`
`after`	`datetime \| str`	Datetime object or ISO date/time string. Only measurements assigned to a time after this date are included.	`None`
`min_age`	`timedelta`	Timedelta object. Only measurements of at least this age are included.	`None`
`max_age`	`timedelta`	Timedelta object. Only measurements with at most this age are included.	`None`
`asc`	`bool`	Return results in ascending (oldest first) order if True, descending (newest first) if False. None uses the server default (ascending for Measurements).	`None`
`revert`	`bool`	The c8y-native server param. `True` flips the default order to descending. If both `asc` and `revert` are supplied, `revert` wins.	`None`

Returns:

Type	Description
`Series`	A Series object which wraps the raw JSON result but can also be
`Series`	used to conveniently collect the series' values.

See also: https://cumulocity.com/api/core/#operation/getMeasurementSeriesResource

select(expression: str | None = None, *, type: str | None = None, source: str | None = None, value_fragment_type: str | None = None, value_fragment_series: str | None = None, series: str | None = None, before: str | datetime | None = None, after: str | datetime | None = None, date_from: str | datetime | None = None, date_to: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, asc: bool | None = None, revert: bool | None = None, limit: int | None = 5, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None, **kwargs) -> AsyncIterator[Measurement]

Query the database for measurements and iterate over the results.

This function is implemented in a lazy fashion - results will only be fetched from the database as long there is a consumer for them.

All parameters are considered to be filters, limiting the result set to objects which meet the filters specification. Filters can be combined (within reason).

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`type`	`str`	Alarm type	`None`
`source`	`str`	Database ID of a source device	`None`
`value_fragment_type`	`str`	The series' value fragment name (e.g. c8y_Environment)	`None`
`value_fragment_series`	`str`	The series' name (within the value fragment, e.g. Temperature)	`None`
`series`	`str`	Full name of a present series within a value fragment e.g. "c8y_Environment.Temperature"	`None`
`before`	`datetime \| str`	Datetime object or ISO date/time string. Only measurements assigned to a time before this date are returned.	`None`
`after`	`datetime \| str`	Datetime object or ISO date/time string. Only measurements assigned to a time after this date are returned.	`None`
`date_from`	`str \| datetime`	Same as `after`	`None`
`date_to`	`str \| datetime`	Same as `before`	`None`
`min_age`	`timedelta`	Timedelta object. Only measurements of at least this age are returned.	`None`
`max_age`	`timedelta`	Timedelta object. Only measurements with at most this age are returned.	`None`
`asc`	`bool`	Return results in ascending (oldest first) order if True, descending (newest first) if False. None uses the server default (ascending for Measurements).	`None`
`revert`	`bool`	Reverse the default ordering.	`None`
`limit`	`int \| None`	Maximum number of results. Default is 5 to support quick Jupyter-style exploration; pass `None` to fetch all matching.	`5`
`page_size`	`int \| None`	Number of records read per request. If None (default), inferred from `limit` and whether client-side filters are set.	`None`
`page_number`	`int`	Pull a specific page; this effectively disables automatic follow-up page retrieval.	`None`
`as_values`	`str \| tuple \| Sequence[str \| tuple] \| None`	(*str\|tuple): Don't parse objects, but directly extract the values at certain JSON paths as tuples; If the path is not defined in a result, None is used; Specify a tuple to define a proper default value for each path.	`None`

Returns:

Type	Description
`AsyncIterator[Measurement]`	Async iterator for matching Measurement objects or values/value tuples if the `as_values` parameter is defined.

`Events`

Provides access to the Events API.

This class can be used for get, search for, create, update and delete events within the Cumulocity database.

See also: https://cumulocity.com/api/core/#tag/Events

`apply_to(model: dict | Event, *event_ids: str, workers: int | None = None) -> None` `async`

Apply a model event (or dict) to a set of existing events.

Parameters:

Name	Type	Description	Default
`model`	`dict \| Event`	Template event or dict with changes to apply	required
`*event_ids`	`str`	Database IDs of events to update	`()`
`workers`	`int`	Number of parallel workers	`None`

`build_attachment_path(event_id: str) -> str`

Build the attachment path of a specific event.

Parameters:

Name	Type	Description	Default
`event_id`	`str`	Database ID of the event	required

Returns:

Type	Description
`str`	The relative path to the event attachment within Cumulocity.

`create(*events: Event, workers: int | None = None) -> None` `async`

Create event objects within the database.

Parameters:

Name	Type	Description	Default
`*events`	`Event`	Collection of Event instances	`()`
`workers`	`int`	Number of parallel workers	`None`

`create_attachment(event_id: str, file: FileSpec, content_type: str | None = None) -> dict` `async`

Add a binary attachment to an event.

Parameters:

Name	Type	Description	Default
`event_id`	`str`	The database ID of the event	required
`file`	`str \| PathLike \| BinaryIO`	File-like object or a file path	required
`content_type`	`str`	Content type of the file sent	`None`

Returns:

Type	Description
`dict`	Attachment details as JSON object (dict).

`delete(*events: str | Event, workers: int | None = None) -> None` `async`

Delete event objects from the database.

Parameters:

Name	Type	Description	Default
`*events`	`str \| Event`	Collection of Event instances or IDs	`()`
`workers`	`int`	Number of parallel workers	`None`

`delete_attachment(event_id: str) -> None` `async`

Remove a binary attachment from an event.

Parameters:

Name	Type	Description	Default
`event_id`	`str`	The database ID of the event	required

`delete_by(expression: str | None = None, *, type: str | None = None, source: str | None = None, fragment: str | None = None, before: str | datetime | None = None, after: str | datetime | None = None, date_from: str | datetime | None = None, date_to: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, **kwargs) -> None` `async`

Query the database and delete matching events.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`type`	`str`	Event type	`None`
`source`	`str`	Database ID of a source device	`None`
`fragment`	`str`	Name of a present custom/standard fragment	`None`
`before`	`str \| datetime`	Only events before this date are deleted.	`None`
`after`	`str \| datetime`	Only events after this date are deleted.	`None`
`date_from`	`str \| datetime`	Same as `after`	`None`
`date_to`	`str \| datetime`	Same as `before`	`None`
`min_age`	`timedelta`	Minimum age for selected events.	`None`
`max_age`	`timedelta`	Maximum age for selected events.	`None`

`download_attachment(event_id: str) -> bytes` `async`

Read a binary attachment of an event.

Parameters:

Name	Type	Description	Default
`event_id`	`str`	The database ID of the event	required

Returns:

Type	Description
`bytes`	The event's binary attachment as bytes.

`get(event_id: str) -> Event` `async`

Retrieve a specific event from the database.

Parameters:

Name	Type	Description	Default
`event_id`	`str`	The database ID of the event	required

Returns:

Type	Description
`Event`	An Event instance representing the object in the database.

get_all(expression: str | None = None, *, type: str | None = None, source: str | None = None, fragment: str | None = None, fragment_type: str | None = None, fragment_value: str | None = None, before: str | datetime | None = None, after: str | datetime | None = None, date_from: str | datetime | None = None, date_to: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, created_before: str | datetime | None = None, created_after: str | datetime | None = None, created_from: str | datetime | None = None, created_to: str | datetime | None = None, updated_before: str | datetime | None = None, updated_after: str | datetime | None = None, last_updated_from: str | datetime | None = None, last_updated_to: str | datetime | None = None, with_source_assets: bool | None = None, with_source_devices: bool | None = None, asc: bool | None = None, revert: bool | None = None, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, limit: int | None = 5, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None, **kwargs) -> list[Event] `async`

Query the database for events and return the results as list.

This function is a greedy version of the select function. All available results are read immediately and returned as list.

See select for a documentation of arguments.

Returns:

Type	Description
`list[Event]`	List of Event objects

get_count(expression: str | None = None, *, type: str | None = None, source: str | None = None, fragment: str | None = None, fragment_type: str | None = None, fragment_value: str | None = None, before: str | datetime | None = None, after: str | datetime | None = None, date_from: str | datetime | None = None, date_to: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, created_before: str | datetime | None = None, created_after: str | datetime | None = None, created_from: str | datetime | None = None, created_to: str | datetime | None = None, updated_before: str | datetime | None = None, updated_after: str | datetime | None = None, last_updated_from: str | datetime | None = None, last_updated_to: str | datetime | None = None, **kwargs) -> int `async`

Calculate the number of potential results of a database query.

This function uses the same parameters as the select function.

Returns:

Type	Description
`int`	Number of potential results

`get_last(expression: str | None = None, *, type: str | None = None, source: str | None = None, fragment: str | None = None, fragment_type: str | None = None, fragment_value: str | None = None, before: str | datetime | None = None, date_to: str | datetime | None = None, min_age: str | timedelta | None = None, with_source_assets: bool | None = None, with_source_devices: bool | None = None, **kwargs) -> Event | None` `async`

Retrieve the most recent matching event.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`type`	`str`	Event type	`None`
`source`	`str`	Database ID of a source device	`None`
`fragment`	`str`	Name of a present custom/standard fragment	`None`
`fragment_type`	`str`	Type of a present custom/standard fragment	`None`
`fragment_value`	`str`	Value of a present custom/standard fragment	`None`
`before`	`str \| datetime`	Upper time bound	`None`
`date_to`	`str \| datetime`	Same as `before`	`None`
`min_age`	`timedelta`	Minimum age for selected events.	`None`
`with_source_assets`	`bool`	Whether to include events for related assets.	`None`
`with_source_devices`	`bool`	Whether to include events for related devices.	`None`

Returns:

Type	Description
`Event \| None`	The most recent Event, or None if no match is found.

select(expression: str | None = None, *, type: str | None = None, source: str | None = None, fragment: str | None = None, fragment_type: str | None = None, fragment_value: str | None = None, before: str | datetime | None = None, after: str | datetime | None = None, date_from: str | datetime | None = None, date_to: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, created_before: str | datetime | None = None, created_after: str | datetime | None = None, created_from: str | datetime | None = None, created_to: str | datetime | None = None, updated_before: str | datetime | None = None, updated_after: str | datetime | None = None, last_updated_from: str | datetime | None = None, last_updated_to: str | datetime | None = None, with_source_assets: bool | None = None, with_source_devices: bool | None = None, asc: bool | None = None, revert: bool | None = None, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, limit: int | None = 5, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None, **kwargs) -> AsyncIterator[Event]

Query the database for events and iterate over the results.

This function is implemented in a lazy fashion - results will only be fetched from the database as long there is a consumer for them.

All parameters are considered to be filters, limiting the result set to objects which meet the filter's specification. Filters can be combined (within reason).

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`type`	`str`	Event type	`None`
`source`	`str`	Database ID of a source device	`None`
`fragment`	`str`	Name of a present custom/standard fragment	`None`
`fragment_type`	`str`	Type of a present custom/standard fragment	`None`
`fragment_value`	`str`	Value of a present custom/standard fragment	`None`
`before`	`str \| datetime`	Datetime object or ISO date/time string. Only events assigned to a time before this date are returned.	`None`
`after`	`str \| datetime`	Datetime object or ISO date/time string. Only events assigned to a time after this date are returned.	`None`
`date_from`	`str \| datetime`	Same as `after`	`None`
`date_to`	`str \| datetime`	Same as `before`	`None`
`min_age`	`timedelta`	Minimum age for selected events.	`None`
`max_age`	`timedelta`	Maximum age for selected events.	`None`
`created_before`	`str \| datetime`	Only events created before this date are returned.	`None`
`created_after`	`str \| datetime`	Only events created after this date are returned.	`None`
`created_from`	`str \| datetime`	Same as `created_after`	`None`
`created_to`	`str \| datetime`	Same as `created_before`	`None`
`updated_before`	`str \| datetime`	Only events updated before this date are returned.	`None`
`updated_after`	`str \| datetime`	Only events updated after this date are returned.	`None`
`last_updated_from`	`str \| datetime`	Same as `updated_after`	`None`
`last_updated_to`	`str \| datetime`	Same as `updated_before`	`None`
`with_source_assets`	`bool`	Whether also events for related source assets should be included. Requires `source`.	`None`
`with_source_devices`	`bool`	Whether also events for related source devices should be included. Requires `source`.	`None`
`asc`	`bool`	Return results in ascending (oldest first) order if True, descending (newest first) if False. None (default) lets the server apply its default order (descending for Events).	`None`
`revert`	`bool`	Reverse the default ordering.	`None`
`limit`	`int \| None`	Maximum number of results; pass `None` to fetch all.	`5`
`include`	`str \| JsonMatcher`	Client-side inclusion filter.	`None`
`exclude`	`str \| JsonMatcher`	Client-side exclusion filter.	`None`
`page_size`	`int \| None`	Number of records read per request. If None (default), inferred from `limit` and whether client-side filters are set.	`None`
`page_number`	`int`	Pull a specific page only.	`None`
`as_values`	`str \| tuple \| Sequence[str \| tuple] \| None`	Extract values at JSON paths as tuples.	`None`
`workers`	`int`	Number of parallel page-fetch workers.	`None`

Returns:

Type	Description
`AsyncIterator[Event]`	AsyncIterator of Event objects

`update(*events: Event, workers: int | None = None) -> None` `async`

Write changes to the database.

Parameters:

Name	Type	Description	Default
`*events`	`Event`	Collection of Event instances	`()`
`workers`	`int`	Number of parallel workers	`None`

`update_attachment(event_id: str, file: FileSpec, content_type: str | None = None) -> dict` `async`

Update a binary attachment of an event.

Parameters:

Name	Type	Description	Default
`event_id`	`str`	The database ID of the event	required
`file`	`str \| PathLike \| BinaryIO`	File-like object or a file path	required
`content_type`	`str`	Content type of the file sent	`None`

Returns:

Type	Description
`dict`	Attachment details as JSON object (dict).

`Alarms`

apply_by(alarm: dict | Alarm, expression: str | None = None, *, type: str | None = None, source: str | None = None, fragment: str | None = None, status: str | None = None, severity: str | None = None, resolved: str | None = None, date_from: str | datetime | None = None, date_to: str | datetime | None = None, before: str | datetime | None = None, after: str | datetime | None = None, created_before: str | datetime | None = None, created_after: str | datetime | None = None, created_from: str | datetime | None = None, created_to: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, with_source_children: bool | None = None, with_source_assets: bool | None = None, with_source_devices: bool | None = None, with_source_additions: bool | None = None, **kwargs) `async`

Apply changes made to a single instance to other objects in the database.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`alarm`	`Alarm`	Object serving as model for the update	required
`type`	`str`	Alarm type	`None`
`source`	`str`	Database ID of a source device	`None`
`fragment`	`str`	Name of a present custom/standard fragment	`None`
`status`	`str`	Alarm status	`None`
`severity`	`str`	Alarm severity	`None`
`resolved`	`str`	Whether the alarm status is CLEARED	`None`
`before`	`str \| datetime`	Datetime object or ISO date/time string. Only alarms assigned to a time before this date are returned.	`None`
`after`	`str \| datetime`	Datetime object or ISO date/time string. Only alarms assigned to a time after this date are returned	`None`
`created_before`	`str \| datetime`	Datetime object or ISO date/time string. Only alarms changed at a time before this date are returned.	`None`
`created_after`	`str \| datetime`	Datetime object or ISO date/time string. Only alarms changed at a time after this date are returned.	`None`
`date_from`	`str \| datetime`	Same as `after`	`None`
`date_to`	`str \| datetime`	Same as `before`	`None`
`created_from`	`str \| datetime`	Same as `created_after`	`None`
`created_to`	`str \| datetime`	Same as `created_before`	`None`
`min_age`	`timedelta`	Matches only alarms of at least this age	`None`
`max_age`	`timedelta`	Matches only alarms with at most this age	`None`
`with_source_children`	`bool`	Whether also alarms for related source children should be included. Requires `source`.	`None`
`with_source_assets`	`bool`	Whether also alarms for related source assets should be included. Requires `source`.	`None`
`with_source_devices`	`bool`	Whether also alarms for related source devices should be included. Requires `source`	`None`
`with_source_additions`	`bool`	Whether also alarms for related source additions should be included. Requires `source`.	`None`

See also: https://cumulocity.com/api/#operation/putAlarmCollectionResource

`apply_to(alarm: Alarm | dict, *alarm_ids: str, workers: int | None = None)` `async`

Apply changes made to a single instance to other objects in the database.

Parameters:

Name	Type	Description	Default
`alarm`	`Alarm \| dict`	Object serving as model for the update or simply a dictionary representing the diff JSON.	required
`*alarm_ids`	`str`	A collection of database IDS of alarms	`()`
`workers`	`int`	The number of parallel processes to use	`None`

count(expression: str | None = None, *, type: str | None = None, source: str | None = None, status: str | None = None, resolved: str | None = None, severity: str | None = None, fragment: str | None = None, before: str | datetime | None = None, after: str | datetime | None = None, date_from: str | datetime | None = None, date_to: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, with_source_children: bool | None = None, with_source_assets: bool | None = None, with_source_devices: bool | None = None, with_source_additions: bool | None = None, **kwargs) -> int `async`

Count the number of certain alarms.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`type`	`str`	Alarm type	`None`
`source`	`str`	Database ID of a source device	`None`
`fragment`	`str`	Name of a present custom/standard fragment	`None`
`status`	`str`	Alarm status	`None`
`severity`	`str`	Alarm severity	`None`
`resolved`	`str`	Whether the alarm status is CLEARED	`None`
`before`	`str \| datetime`	Datetime object or ISO date/time string. Only alarms assigned to a time before this date are returned.	`None`
`after`	`str \| datetime`	Datetime object or ISO date/time string. Only alarms assigned to a time after this date are returned	`None`
`date_from`	`str \| datetime`	Same as `after`	`None`
`date_to`	`str \| datetime`	Same as `before`	`None`
`min_age`	`timedelta`	Matches only alarms of at least this age	`None`
`max_age`	`timedelta`	Matches only alarms with at most this age	`None`
`with_source_children`	`bool`	Whether also alarms for related source children should be included. Requires `source`.	`None`
`with_source_assets`	`bool`	Whether also alarms for related source assets should be included. Requires `source`.	`None`
`with_source_devices`	`bool`	Whether also alarms for related source devices should be included. Requires `source`	`None`
`with_source_additions`	`bool`	Whether also alarms for related source additions should be included. Requires `source`	`None`

Returns:

Type	Description
`int`	Number of matching alarms in Cumulocity.

`create(*alarms: Alarm, workers: int | None = None) -> None` `async`

Create alarm objects within the database.

Parameters:

Name	Type	Description	Default
`*alarms`	`Alarm`	Collection of Alarm instances	`()`
`workers`	`int`	The number of parallel processes to use	`None`

`delete(*alarms: str | Alarm, workers: int | None = None) -> None` `async`

Delete alarm objects from the database.

Parameters:

Name	Type	Description	Default
`*alarms`	`str \| Alarm`	Collection of Alarm instances or IDs	`()`
`workers`	`int`	The number of parallel processes to use	`None`

delete_by(expression: str | None = None, *, type: str | None = None, source: str | None = None, fragment: str | None = None, status: str | None = None, severity: str | None = None, resolved: str | None = None, before: str | datetime | None = None, after: str | datetime | None = None, date_from: str | datetime | None = None, date_to: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, created_before: str | datetime | None = None, created_after: str | datetime | None = None, created_from: str | datetime | None = None, created_to: str | datetime | None = None, updated_before: str | datetime | None = None, updated_after: str | datetime | None = None, last_updated_from: str | datetime | None = None, last_updated_to: str | datetime | None = None, with_source_children: bool | None = None, with_source_assets: bool | None = None, with_source_devices: bool | None = None, with_source_additions: bool | None = None, **kwargs) `async`

Query the database and delete matching alarms.

All parameters are considered to be filters, limiting the result set to objects which meet the filters specification. Filters can be combined (as defined in the Cumulocity REST API).

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`type`	`str`	Alarm type	`None`
`source`	`str`	Database ID of a source device	`None`
`fragment`	`str`	Name of a present custom/standard fragment	`None`
`status`	`str`	Alarm status	`None`
`severity`	`str`	Alarm severity	`None`
`resolved`	`str`	Whether the alarm status is CLEARED	`None`
`before`	`str \| datetime`	Datetime object or ISO date/time string. Only alarms assigned to a time before this date are returned.	`None`
`after`	`str \| datetime`	Datetime object or ISO date/time string. Only alarms assigned to a time after this date are returned	`None`
`date_from`	`str \| datetime`	Same as `after`	`None`
`date_to`	`str \| datetime`	Same as `before`	`None`
`min_age`	`timedelta`	Matches only alarms of at least this age	`None`
`max_age`	`timedelta`	Matches only alarms with at most this age	`None`
`created_before`	`str \| datetime`	Datetime object or ISO date/time string. Only alarms changed at a time before this date are returned.	`None`
`created_after`	`str \| datetime`	Datetime object or ISO date/time string. Only alarms changed at a time after this date are returned.	`None`
`created_from`	`str \| datetime`	Same as `created_after`	`None`
`created_to`	`str \| datetime`	Same as `created_before`	`None`
`updated_before`	`str \| datetime`	Datetime object or ISO date/time string. Only alarms changed at a time before this date are returned.	`None`
`updated_after`	`str \| datetime`	Datetime object or ISO date/time string. Only alarms changed at a time after this date are returned.	`None`
`last_updated_from`	`str \| datetime`	Same as `updated_after`	`None`
`last_updated_to`	`str \| datetime`	Same as `updated_before`	`None`
`with_source_children`	`bool`	Whether also alarms for related source children should be included. Requires `source`.	`None`
`with_source_assets`	`bool`	Whether also alarms for related source assets should be included. Requires `source`.	`None`
`with_source_devices`	`bool`	Whether also alarms for related source devices should be included. Requires `source`	`None`
`with_source_additions`	`bool`	Whether also alarms for related source additions should be included. Requires `source`	`None`

`get(id: str) -> Alarm` `async`

Retrieve a specific object from the database.

Parameters:

Name	Type	Description	Default
`id`	`str`	The database ID of the object	required

Returns:

Type	Description
`Alarm`	An Alarm instance representing the object in the database.

get_all(expression: str | None = None, *, type: str | None = None, source: str | None = None, status: str | None = None, resolved: str | None = None, severity: str | None = None, fragment: str | None = None, with_source_assets: bool | None = None, with_source_devices: bool | None = None, before: str | datetime | None = None, after: str | datetime | None = None, date_from: str | datetime | None = None, date_to: str | datetime | None = None, created_before: str | datetime | None = None, created_after: str | datetime | None = None, created_from: str | datetime | None = None, created_to: str | datetime | None = None, updated_before: str | datetime | None = None, updated_after: str | datetime | None = None, last_updated_from: str | datetime | None = None, last_updated_to: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, limit: int | None = 5, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None, **kwargs) -> list[Alarm] `async`

Query the database for alarms and return the results as list.

This function is a greedy version of the select function. All available results are read immediately and returned as list.

See select for a documentation of arguments.

Returns:

Type	Description
`list[Alarm]`	List of Alarm objects

get_count(expression: str | None = None, *, type: str | None = None, source: str | None = None, status: str | None = None, resolved: str | None = None, severity: str | None = None, fragment: str | None = None, before: str | datetime | None = None, after: str | datetime | None = None, date_from: str | datetime | None = None, date_to: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, with_source_children: bool | None = None, with_source_assets: bool | None = None, with_source_devices: bool | None = None, with_source_additions: bool | None = None, **kwargs) -> int `async`

Count the number of certain alarms.

Note: Unlike other collection classes, Alarms has a dedicated /alarms/count endpoint. Consider using count() directly.

See count for a documentation of arguments.

Returns:

Type	Description
`int`	Number of matching alarms in Cumulocity.

select(expression: str | None = None, *, type: str | None = None, source: str | None = None, status: str | None = None, resolved: str | None = None, severity: str | None = None, fragment: str | None = None, before: str | datetime | None = None, after: str | datetime | None = None, date_from: str | datetime | None = None, date_to: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, created_before: str | datetime | None = None, created_after: str | datetime | None = None, created_from: str | datetime | None = None, created_to: str | datetime | None = None, updated_before: str | datetime | None = None, updated_after: str | datetime | None = None, last_updated_from: str | datetime | None = None, last_updated_to: str | datetime | None = None, with_source_children: bool | None = None, with_source_assets: bool | None = None, with_source_devices: bool | None = None, with_source_additions: bool | None = None, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, limit: int | None = 5, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None, **kwargs) -> AsyncIterator[Alarm]

Query the database for alarms and iterate over the results.

This function is implemented in a lazy fashion - results will only be fetched from the database as long there is a consumer for them.

All parameters are considered to be filters, limiting the result set to objects which meet the filters specification. Filters can be combined (as defined in the Cumulocity REST API).

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`type`	`str`	Alarm type	`None`
`source`	`str`	Database ID of a source device	`None`
`fragment`	`str`	Name of a present custom/standard fragment	`None`
`fragment_type`	`str`	Same as `fragment`.	required
`status`	`str`	Alarm status	`None`
`severity`	`str`	Alarm severity	`None`
`resolved`	`str`	Whether the alarm status is CLEARED	`None`
`before`	`str \| datetime`	Datetime object or ISO date/time string. Only alarms assigned to a time before this date are returned.	`None`
`after`	`str \| datetime`	Datetime object or ISO date/time string. Only alarms assigned to a time after this date are returned	`None`
`date_from`	`str \| datetime`	Same as `after`	`None`
`date_to`	`str \| datetime`	Same as `before`	`None`
`min_age`	`timedelta`	Matches only alarms of at least this age	`None`
`max_age`	`timedelta`	Matches only alarms with at most this age	`None`
`created_before`	`str \| datetime`	Datetime object or ISO date/time string. Only alarms changed at a time before this date are returned.	`None`
`created_after`	`str \| datetime`	Datetime object or ISO date/time string. Only alarms changed at a time after this date are returned.	`None`
`created_from`	`str \| datetime`	Same as `created_after`	`None`
`created_to`	`str \| datetime`	Same as `created_before`	`None`
`updated_before`	`str \| datetime`	Datetime object or ISO date/time string. Only alarms changed at a time before this date are returned.	`None`
`updated_after`	`str \| datetime`	Datetime object or ISO date/time string. Only alarms changed at a time after this date are returned.	`None`
`last_updated_from`	`str \| datetime`	Same as `updated_after`	`None`
`last_updated_to`	`str \| datetime`	Same as `updated_before`	`None`
`with_source_children`	`bool`	Whether also alarms for related source children should be included. Requires `source`.	`None`
`with_source_assets`	`bool`	Whether also alarms for related source assets should be included. Requires `source`.	`None`
`with_source_devices`	`bool`	Whether also alarms for related source devices should be included. Requires `source`	`None`
`with_source_additions`	`bool`	Whether also alarms for related source additions should be included. Requires `source`.	`None`
`limit`	`int \| None`	Maximum number of results. Default is 5 to support quick Jupyter-style exploration; pass `None` to fetch all matching.	`5`
`include`	`str \| JsonMatcher`	Matcher/expression to filter the query results (on client side). The inclusion is applied first. Creates a PyDF (Python Display Filter) matcher by default for strings.	`None`
`exclude`	`str \| JsonMatcher`	Matcher/expression to filter the query results (on client side). The exclusion is applied second. Creates a PyDF (Python Display Filter) matcher by default for strings.	`None`
`page_size`	`int \| None`	Number of records read per request. If None (default), inferred from `limit` and whether client-side filters are set.	`None`
`page_number`	`int`	Pull a specific page; this effectively disables automatic follow-up page retrieval.	`None`
`as_values`	`str \| tuple \| Sequence[str \| tuple] \| None`	(str\|tuple\|list[str\|tuple]): Don't parse objects, but directly extract the values at certain JSON paths as tuples; If the path is not defined in a result, None is used; Specify a tuple to define a proper default value for each path.	`None`

Returns:

Type	Description
`AsyncIterator[Alarm]`	Generator of Alarm objects

`update(*alarms: Alarm, workers: int | None = None) -> None` `async`

Write changes to the database.

Parameters:

Name	Type	Description	Default
`*alarms`	`Alarm`	Collection of Alarm instances	`()`
`workers`	`int`	The number of parallel processes to use	`None`

`Users`

Provides access to the User API.

See also: https://cumulocity.com/api/core/#tag/Users

`build_object_path(object_id: str) -> str`

`create(*users: User, workers: int | None = None) -> None` `async`

Create users within the database.

Parameters:

Name	Type	Description	Default
`*users`	`User`	Collection of User instances	`()`
`workers`	`int`	Number of parallel requests	`None`

`delete(*users: str | User, workers: int | None = None) -> None` `async`

Delete users from the database.

Parameters:

Name	Type	Description	Default
`*users`	`str \| User`	User objects or usernames to delete	`()`
`workers`	`int`	Number of parallel requests	`None`

`get(username: str)` `async`

Retrieve a specific user.

Parameters:

Name	Type	Description	Default
`username`	`str`	The ID of the user (usually the mail address)	required

Returns:

Type	Description
	A User instance

get_all(expression: str | None = None, *, username: str | None = None, groups: str | int | UserGroup | Sequence[str | int | UserGroup] | None = None, owner: str | None = None, only_devices: bool | None = None, with_subusers_count: bool | None = None, limit: int | None = 5, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None) -> list[User] `async`

Query the database for users and return the results as a list.

This function is a greedy version of the select function. All available results are read immediately and returned as a list.

See select for a documentation of arguments.

Returns:

Type	Description
`list[User]`	List of User instances

`get_count(expression: str | None = None, *, username: str | None = None, groups: str | int | UserGroup | Sequence[str | int | UserGroup] | None = None, owner: str | None = None, only_devices: bool | None = None) -> int` `async`

Calculate the number of users in the database.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`username`	`str`	Filter by username or username prefix	`None`
`groups`	`int \| str \| UserGroup \| Sequence`	Filter by group membership	`None`
`owner`	`str`	Filter by owner username	`None`
`only_devices`	`bool`	Only count device users (prefixed with `device_`)	`None`

Returns:

Type	Description
`int`	Number of users

`get_current() -> CurrentUser` `async`

Retrieve current user.

Returns:

Type	Description
`CurrentUser`	CurrentUser instance

`get_tfa_settings(user_id: str) -> TfaSettings` `async`

Read the TFA settings of a given user.

Parameters:

Name	Type	Description	Default
`user_id`	`str`	The user to query the settings for	required

Returns:

Type	Description
`TfaSettings`	A TfaSettings object

`logout_all()` `async`

Terminate all user's sessions.

`revoke_totp_secret(user_id: str)` `async`

Revoke the currently set TFA/TOTP secret for a user.

Parameters:

Name	Type	Description	Default
`user_id`	`str`	The user to revoke the totp secret for	required

select(expression: str | None = None, *, username: str | None = None, groups: int | UserGroup | Sequence[int | UserGroup] | None = None, owner: str | None = None, only_devices: bool | None = None, with_subusers_count: bool | None = None, limit: int | None = 5, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None) -> AsyncIterator[User]

Iterate over users.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`username`	`str`	Filter by username or username prefix	`None`
`groups`	`int \| str \| UserGroup \| Sequence`	Filter by group membership; accepts group IDs (int or str) or UserGroup instances; use UserGroups.resolve_group_id to resolve a group name to an ID first	`None`
`owner`	`str`	Filter by owner username	`None`
`only_devices`	`bool`	Only return device users (prefixed with `device_`)	`None`
`with_subusers_count`	`bool`	Include `subusersCount` field in results	`None`
`limit`	`int \| None`	Maximum number of results. Default is 5 to support quick Jupyter-style exploration; pass `None` to fetch all matching.	`5`
`include`	`str \| JsonMatcher`	Client-side inclusion filter	`None`
`exclude`	`str \| JsonMatcher`	Client-side exclusion filter	`None`
`page_size`	`int \| None`	Number of records read per request. If None (default), inferred from `limit` and whether client-side filters are set.	`None`
`page_number`	`int`	Pull a specific page only	`None`
`as_values`	`str \| tuple \| Sequence[str \| tuple] \| None`	Extract values at JSON paths instead of parsing objects	`None`
`workers`	`int`	Number of parallel page requests	`None`

Note

The get_all function supports group names for the groups parameter.

Returns:

Type	Description
`AsyncIterator[User]`	AsyncIterator of User instances

`set_current_password(current_password: str, new_password: str)` `async`

Set the password of the current user.

Note: This automatically updates the connection with the new auth information.

Parameters:

Name	Type	Description	Default
`current_password`	`str`	The current password	required
`new_password`	`str`	The new password to set	required

`set_delegate(user_id: str, delegate_id: str | None)` `async`

Set the delegate of a given user.

Parameters:

Name	Type	Description	Default
`user_id`	`str`	The user to set a delegate for	required
`delegate_id`	`str`	The ID of the delegate user; Can be None to unassign/remove the current delegate	required

`set_owner(user_id: str, owner_id: str | None)` `async`

Set the owner of a given user.

Parameters:

Name	Type	Description	Default
`user_id`	`str`	The user to set an owner for	required
`owner_id`	`str`	The ID of the owner user; Can be None to unassign/remove the current owner	required

`update(*users: User, workers: int | None = None) -> None` `async`

Update users within the database.

Parameters:

Name	Type	Description	Default
`*users`	`User`	Collection of User instances	`()`
`workers`	`int`	Number of parallel requests	`None`

`InventoryRoles`

Provides access to the Inventory Roles API.

See also: https://cumulocity.com/api/core/#tag/Inventory-Roles

`assign(username: str, managed_object_id: str | int, *roles: InventoryRole | int | str) -> InventoryRoleAssignment` `async`

Assign inventory roles for a managed object to a user.

Parameters:

Name	Type	Description	Default
`username`	`str`	Username of the Cumulocity user	required
`managed_object_id`	`str \| int`	ID of the managed object (e.g. device group)	required
`*roles`	`InventoryRole \| int \| str`	Role objects or IDs to assign	`()`

Returns:

Type	Description
`InventoryRoleAssignment`	The created InventoryRoleAssignment

`build_assignment_path(username: str, assignment_id: str | int | None = None) -> str`

Build the URL path for a user's inventory-role assignment(s).

Returns the collection path when assignment_id is omitted, or the path to a single assignment otherwise.

`create(*roles: InventoryRole, workers: int | None = None) -> None` `async`

Create inventory roles within the database.

Parameters:

Name	Type	Description	Default
`*roles`	`InventoryRole`	Collection of InventoryRole instances	`()`
`workers`	`int`	Number of parallel requests	`None`

`delete(*roles: str | int | InventoryRole, workers: int | None = None) -> None` `async`

Delete inventory roles from the database.

Parameters:

Name	Type	Description	Default
`*roles`	`str \| int \| InventoryRole`	Role objects or IDs to delete	`()`
`workers`	`int`	Number of parallel requests	`None`

`get(role_id: int | str) -> InventoryRole` `async`

Retrieve a specific inventory role.

Parameters:

Name	Type	Description	Default
`role_id`	`int \| str`	ID of the inventory role	required

Returns:

Type	Description
`InventoryRole`	An InventoryRole instance

`get_all(expression: str | None = None, *, limit: int | None = 5, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None) -> list[InventoryRole]` `async`

Query the database for inventory roles and return the results as a list.

See select for a documentation of arguments.

Returns:

Type	Description
`list[InventoryRole]`	List of InventoryRole instances

`get_assignments(username: str) -> list[InventoryRoleAssignment]` `async`

Retrieve all inventory role assignments of a user.

Parameters:

Name	Type	Description	Default
`username`	`str`	Username of the Cumulocity user	required

Returns:

Type	Description
`list[InventoryRoleAssignment]`	List of InventoryRoleAssignment instances

`reassign(username: str, assignment_id: str | int, managed_object_id: str | int, *roles: InventoryRole | int | str) -> InventoryRoleAssignment` `async`

Replace an existing inventory role assignment.

Note: The Cumulocity API replaces the assignment entirely; the previous set of roles is not preserved or merged. Pass the full intended set of roles.

Parameters:

Name	Type	Description	Default
`username`	`str`	Username of the Cumulocity user	required
`assignment_id`	`str \| int`	ID of the existing assignment to replace	required
`managed_object_id`	`str \| int`	ID of the managed object (e.g. device group)	required
`*roles`	`InventoryRole \| int \| str`	Role objects or IDs to assign	`()`

Returns:

Type	Description
`InventoryRoleAssignment`	The updated InventoryRoleAssignment

`select(expression: str | None = None, *, limit: int | None = 5, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None) -> AsyncIterator[InventoryRole]`

Iterate over all defined inventory roles.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`limit`	`int \| None`	Maximum number of results. Default is 5 to support quick Jupyter-style exploration; pass `None` to fetch all matching.	`5`
`include`	`str \| JsonMatcher`	Client-side inclusion filter.	`None`
`exclude`	`str \| JsonMatcher`	Client-side exclusion filter.	`None`
`page_size`	`int \| None`	Number of records read per request. If None (default), inferred from `limit` and whether client-side filters are set.	`None`
`page_number`	`int`	Pull a specific page only	`None`
`as_values`	`str \| tuple \| Sequence[str \| tuple] \| None`	Extract values at JSON paths instead of parsing objects	`None`
`workers`	`int`	Number of parallel page requests	`None`

Returns:

Type	Description
`AsyncIterator[InventoryRole]`	AsyncIterator of InventoryRole instances

`unassign(username: str, *assignment_ids: str | int, workers: int | None = None) -> None` `async`

Remove inventory role assignments from a user.

Parameters:

Name	Type	Description	Default
`username`	`str`	Username of the Cumulocity user	required
`*assignment_ids`	`str \| int`	IDs of existing inventory role assignments	`()`
`workers`	`int`	Number of parallel requests; defaults to sequential	`None`

Raises:

Type	Description
`BatchError`	If one or more individual deletes fail.

`unassign_by(username: str, *objects: str | ManagedObject, workers: int | None = None) -> None` `async`

Remove a user's inventory role assignments by managed object.

Convenience method, not backed by a single API call: this first reads all the user's assignments, then deletes the matching ones individually by ID.

Parameters:

Name	Type	Description	Default
`username`	`str`	Username of the Cumulocity user	required
`*objects`	`str \| ManagedObject`	Managed objects (or IDs) whose assignments should be removed; if omitted, all assignments for this user are removed. Missing matches are silently ignored.	`()`
`workers`	`int`	Number of parallel requests; defaults to sequential	`None`

Raises:

Type	Description
`BatchError`	If one or more individual deletes fail.

`update(*roles: InventoryRole, workers: int | None = None) -> None` `async`

Update inventory roles within the database.

Parameters:

Name	Type	Description	Default
`*roles`	`InventoryRole`	Collection of InventoryRole instances	`()`
`workers`	`int`	Number of parallel requests	`None`

`Subscriptions`

Provides access to the Notification 2.0 Subscriptions API.

This class can be used for get, search for, create, and delete Notification2 subscriptions within the Cumulocity database.

https://cumulocity.com/api/core/#tag/Subscriptions

https://cumulocity.com/guides/reference/notifications/

`create(*subscriptions: Subscription, workers: int | None = None) -> None` `async`

Create subscriptions within the database.

Parameters:

Name	Type	Description	Default
`*subscriptions`	`Subscription`	Collection of Subscription instances	`()`
`workers`	`int`	Number of parallel workers	`None`

`delete_by(expression: str | None = None, *, context: str | None = None, source: str | None = None) -> None` `async`

Delete subscriptions within the database.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`context`	`str`	Subscription context	`None`
`source`	`str`	Managed object ID the subscription is for	`None`

`get(subscription_id: str) -> Subscription` `async`

Retrieve a specific subscription from the database.

Parameters:

Name	Type	Description	Default
`subscription_id`	`str`	Subscription ID	required

Returns:

Type	Description
`Subscription`	A Subscription instance

`get_all(expression: str | None = None, *, context: str | None = None, source: str | None = None, subscription: str | None = None, type_filter: str | None = None, limit: int | None = 5, page_size: int | None = None, page_number: int | None = None, workers: int | None = None, **kwargs) -> list[Subscription]` `async`

Query the database for subscriptions and return the results as list.

See select for a documentation of arguments.

Returns:

Type	Description
`list[Subscription]`	List of Subscription instances

`get_count(expression: str | None = None, *, context: str | None = None, source: str | None = None, subscription: str | None = None, type_filter: str | None = None, **kwargs) -> int` `async`

Calculate the number of potential results of a database query.

Returns:

Type	Description
`int`	Number of potential results

`select(expression: str | None = None, *, context: str | None = None, source: str | None = None, subscription: str | None = None, type_filter: str | None = None, limit: int | None = 5, page_size: int | None = None, page_number: int | None = None, workers: int | None = None, **kwargs) -> AsyncIterator[Subscription]`

Query the database for subscriptions and iterate over the results.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression; all other filters are ignored if this is provided	`None`
`context`	`str`	Subscription context	`None`
`source`	`str`	Managed object ID the subscription is for	`None`
`subscription`	`str`	The subscription name	`None`
`type_filter`	`str`	Object type filter	`None`
`limit`	`int \| None`	Maximum number of results. Default is 5 to support quick Jupyter-style exploration; pass `None` to fetch all matching.	`5`
`page_size`	`int \| None`	Number of records read per request. If None (default), inferred from `limit` and whether client-side filters are set.	`None`
`page_number`	`int`	Pull a specific page only	`None`
`workers`	`int`	Number of parallel page-fetch workers	`None`

Returns:

Type	Description
`AsyncIterator[Subscription]`	AsyncIterator of Subscription instances

`Tokens`

Provides access to the Notification 2.0 token generation API.

https://cumulocity.com/api/core/#tag/Tokens

https://cumulocity.com/guides/reference/notifications/

`init(c8y: CumulocityRestClient)`

`build_websocket_uri(token: str, consumer: str | None = None) -> str`

Build websocket access URL.

Parameters:

Name	Type	Description	Default
`token`	`str`	Subscriber access token	required
`consumer`	`str`	Optional consumer ID for sticky connections	`None`

Returns:

Type	Description
`str`	A websocket (ws(s)://) URL to access the subscriber channel

`generate(subscription: str, expires: int = 1440, subscriber: str | None = None, signed: bool | None = None, shared: bool | None = None, non_persistent: bool | None = None) -> str` `async`

Generate a new access token.

Parameters:

Name	Type	Description	Default
`subscription`	`str`	Subscription name	required
`expires`	`int`	Expiration time in minutes	`1440`
`subscriber`	`str`	Subscriber ID; a UUID-based default is used if None	`None`
`signed`	`bool`	Whether the token should be signed	`None`
`shared`	`bool`	Whether the token is used to create a shared consumer	`None`
`non_persistent`	`bool`	Whether the token refers to the non-persistent subscription	`None`

Returns:

Type	Description
`str`	JWT access token as string

`unsubscribe(token: str) -> None` `async`

Invalidate a token and unsubscribe a subscriber.

Parameters:

Name	Type	Description	Default
`token`	`str`	Subscribed token	required

`Operations`

Provides access to the Operations API.

This class can be used for get, search for, create, update and delete operations within the Cumulocity database.

See also: https://cumulocity.com/api/core/#tag/Operations

`create(*operations: Operation, workers: int | None = None) -> None` `async`

Create operation objects within the database.

Parameters:

Name	Type	Description	Default
`*operations`	`Operation`	Collection of Operation instances	`()`
`workers`	`int`	Number of parallel workers	`None`

`delete_by(expression: str | None = None, *, agent_id: str | None = None, device_id: str | None = None, status: str | None = None, bulk_id: str | None = None, fragment: str | None = None, before: str | datetime | None = None, after: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, **kwargs) -> None` `async`

Query the database and delete matching operations.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression; all other filters are ignored if this is provided	`None`
`agent_id`	`str`	Database ID of agent	`None`
`device_id`	`str`	Database ID of device	`None`
`status`	`str`	Operation status	`None`
`bulk_id`	`str`	Bulk operation ID	`None`
`fragment`	`str`	Name of a present custom fragment	`None`
`before`	`str \| datetime`	Only operations before this date	`None`
`after`	`str \| datetime`	Only operations after this date	`None`
`min_age`	`timedelta \| str`	Minimum age	`None`
`max_age`	`timedelta \| str`	Maximum age	`None`

`get(operation_id: str) -> Operation` `async`

Read a specific operation from the database.

Parameters:

Name	Type	Description	Default
`operation_id`	`str`	Database ID of the operation	required

Returns:

Type	Description
`Operation`	Operation object

get_all(expression: str | None = None, *, agent_id: str | None = None, device_id: str | None = None, status: str | None = None, bulk_id: str | None = None, fragment: str | None = None, before: str | datetime | None = None, after: str | datetime | None = None, date_from: str | datetime | None = None, date_to: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, asc: bool | None = None, revert: bool | None = None, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, limit: int | None = 5, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None, **kwargs) -> list[Operation] `async`

Query the database for operations and return the results as list.

See select for a documentation of arguments.

Returns:

Type	Description
`list[Operation]`	List of matching Operation objects

`get_count(expression: str | None = None, *, agent_id: str | None = None, device_id: str | None = None, status: str | None = None, bulk_id: str | None = None, fragment: str | None = None, before: str | datetime | None = None, after: str | datetime | None = None, date_from: str | datetime | None = None, date_to: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, **kwargs) -> int` `async`

Calculate the number of potential results of a database query.

Returns:

Type	Description
`int`	Number of potential results

`get_last(expression: str | None = None, *, agent_id: str | None = None, device_id: str | None = None, status: str | None = None, bulk_id: str | None = None, fragment: str | None = None, date_to: str | datetime | None = None, before: str | datetime | None = None, min_age: str | timedelta | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, **kwargs) -> Operation | None` `async`

Query the database and return the last matching operation.

Returns:

Type	Description
`Operation \| None`	Last matching Operation object or None

select(expression: str | None = None, *, agent_id: str | None = None, device_id: str | None = None, status: str | None = None, bulk_id: str | None = None, fragment: str | None = None, before: str | datetime | None = None, after: str | datetime | None = None, date_from: str | datetime | None = None, date_to: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, asc: bool | None = None, revert: bool | None = None, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, limit: int | None = 5, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None, **kwargs) -> AsyncIterator[Operation]

Query the database for operations and iterate over the results.

This function is implemented in a lazy fashion - results will only be fetched from the database as long as there is a consumer for them.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression; all other filters are ignored if this is provided	`None`
`agent_id`	`str`	Database ID of agent	`None`
`device_id`	`str`	Database ID of device	`None`
`status`	`str`	Operation status	`None`
`bulk_id`	`str`	The bulk operation ID that this object belongs to	`None`
`fragment`	`str`	Name of a present custom/standard fragment	`None`
`before`	`str \| datetime`	Only operations before this date	`None`
`after`	`str \| datetime`	Only operations after this date	`None`
`date_from`	`str \| datetime`	Same as `after`	`None`
`date_to`	`str \| datetime`	Same as `before`	`None`
`min_age`	`timedelta \| str`	Minimum age for selected operations	`None`
`max_age`	`timedelta \| str`	Maximum age for selected operations	`None`
`asc`	`bool`	Return results in ascending (oldest first) order if True, descending (newest first) if False. None (default) uses the server default (ascending for Operations).	`None`
`revert`	`bool`	Reverse the default ordering.	`None`
`include`	`str \| JsonMatcher`	Client-side inclusion filter	`None`
`exclude`	`str \| JsonMatcher`	Client-side exclusion filter	`None`
`limit`	`int \| None`	Maximum number of results. Default is 5 to support quick Jupyter-style exploration; pass `None` to fetch all matching.	`5`
`page_size`	`int \| None`	Number of records read per request. If None (default), inferred from `limit` and whether client-side filters are set.	`None`
`page_number`	`int`	Pull a specific page only	`None`
`as_values`	`str \| tuple \| Sequence[str \| tuple] \| None`	Extract values at JSON paths as tuples	`None`
`workers`	`int`	Number of parallel page-fetch workers	`None`

Returns:

Type	Description
`AsyncIterator[Operation]`	AsyncIterator of Operation objects

`update(*operations: Operation, workers: int | None = None) -> None` `async`

Update operation objects within the database.

Parameters:

Name	Type	Description	Default
`*operations`	`Operation`	Collection of Operation instances	`()`
`workers`	`int`	Number of parallel workers	`None`

`BulkOperations`

Provides access to the Bulk Operations API.

This class can be used for get, search for, create, update and delete bulk operations within the Cumulocity database.

See also: https://cumulocity.com/api/core/#tag/Bulk-operations

`create(*operations: BulkOperation, workers: int | None = None) -> None` `async`

Create bulk operation objects within the database.

Parameters:

Name	Type	Description	Default
`*operations`	`BulkOperation`	Collection of BulkOperation instances	`()`
`workers`	`int`	Number of parallel workers	`None`

`get(operation_id: str) -> BulkOperation` `async`

Read a specific bulk operation from the database.

Parameters:

Name	Type	Description	Default
`operation_id`	`str`	Database ID of the bulk operation	required

Returns:

Type	Description
`BulkOperation`	BulkOperation object

`get_all(expression: str | None = None, *, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, limit: int | None = 5, page_size: int | None = None, page_number: int | None = None, workers: int | None = None, **kwargs) -> list[BulkOperation]` `async`

Query the database for bulk operations and return the results as list.

See select for a documentation of arguments.

Returns:

Type	Description
`list[BulkOperation]`	List of BulkOperation objects

`get_count(expression: str | None = None, **kwargs) -> int` `async`

Calculate the number of potential results of a database query.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`

Returns:

Type	Description
`int`	Number of potential results

`select(expression: str | None = None, *, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, limit: int | None = 5, page_size: int | None = None, page_number: int | None = None, workers: int | None = None, **kwargs) -> AsyncIterator[BulkOperation]`

Query the database for bulk operations and iterate over the results.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`include`	`str \| JsonMatcher`	Client-side inclusion filter	`None`
`exclude`	`str \| JsonMatcher`	Client-side exclusion filter	`None`
`limit`	`int \| None`	Maximum number of results. Default is 5 to support quick Jupyter-style exploration; pass `None` to fetch all matching.	`5`
`page_size`	`int \| None`	Number of records read per request. If None (default), inferred from `limit` and whether client-side filters are set.	`None`
`page_number`	`int`	Pull a specific page only	`None`
`workers`	`int`	Number of parallel page-fetch workers	`None`

Returns:

Type	Description
`AsyncIterator[BulkOperation]`	AsyncIterator of BulkOperation objects

`update(*operations: BulkOperation, workers: int | None = None) -> None` `async`

Update bulk operation objects within the database.

Parameters:

Name	Type	Description	Default
`*operations`	`BulkOperation`	Collection of BulkOperation instances	`()`
`workers`	`int`	Number of parallel workers	`None`

`Applications`

Provides access to the Application API.

This class can be used to get, search for, create, update and delete applications within the Cumulocity database.

See also: https://cumulocity.com/api/#tag/Application-API

`create(*applications: Application, workers: int | None = None) -> None` `async`

Create application objects within the database.

Parameters:

Name	Type	Description	Default
`*applications`	`Application`	Collection of Application instances	`()`
`workers`	`int`	The number of parallel processes to use	`None`

`delete(*applications: str | Application, workers: int | None = None) -> None` `async`

Delete application objects within the database.

Parameters:

Name	Type	Description	Default
`*applications`	`str \| Application`	Collection of Application instances or IDs	`()`
`workers`	`int`	The number of parallel processes to use	`None`

`get(application_id: str) -> Application` `async`

Retrieve a specific application from the database.

Parameters:

Name	Type	Description	Default
`application_id`	`str`	The database ID of the application	required

Returns:

Type	Description
`Application`	An Application instance representing the object in the database.

get_all(expression: str | None = None, *, name: str | None = None, type: str | None = None, owner: str | None = None, user: str | None = None, tenant: str | None = None, subscriber: str | None = None, provided_for: str | None = None, has_versions: bool | None = None, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, limit: int | None = 5, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None, **kwargs) -> list[Application] `async`

Query the database for applications and return the results as list.

This function is a greedy version of the select function. All available results are read immediately and returned as list.

See select for a documentation of arguments.

Returns:

Type	Description
`list[Application]`	List of Application objects

`get_current() -> Application` `async`

Retrieve the current application.

Note: Requires bootstrap permissions.

Returns:

Type	Description
`Application`	An Application instance.

`get_current_settings() -> dict[str, str]` `async`

Query the database for the current application's settings, i.e. tenant options.

The tenant option category is determined by application's settings category, name or context path.

Note: Requires bootstrap permissions or service user permissions.

Caveat: this function does not remove the credentials. prefix of encrypted tenant options.

Returns:

Type	Description
`dict[str, str]`	Dictionary of tenant option values by key.

See also: TenantOptions.get_values to read tenant options

`get_current_subscriptions() -> list[ApplicationSubscription]` `async`

Query the database for subscriptions of the current application.

Note: Requires bootstrap permissions.

Returns:

Type	Description
`list[ApplicationSubscription]`	List of ApplicationSubscription instances.

select(expression: str | None = None, *, name: str | None = None, type: str | None = None, owner: str | None = None, user: str | None = None, tenant: str | None = None, subscriber: str | None = None, provided_for: str | None = None, has_versions: bool | None = None, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, limit: int | None = 5, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None, **kwargs) -> AsyncIterator[Application]

Query the database for applications and iterate over the results.

This function is implemented in a lazy fashion - results will only be fetched from the database as long as there is a consumer for them.

All parameters are considered to be filters, limiting the result set to objects which meet the filters' specification. Filters can be combined (within reason).

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`name`	`str`	Name of an application (no wildcards allowed)	`None`
`type`	`str`	Application type (e.g. HOSTED)	`None`
`owner`	`str`	ID of a Cumulocity user which owns the application	`None`
`user`	`str`	ID of a Cumulocity user which has general access	`None`
`tenant`	`str`	ID of a Cumulocity tenant which either owns the application or is subscribed to it	`None`
`subscriber`	`str`	ID of a Cumulocity tenant which is subscribed to the application (and may own it)	`None`
`provided_for`	`str`	ID of a Cumulocity tenant which is subscribed to the application but does not own it	`None`
`has_versions`	`bool`	Whether to filter for applications with a defined applicationVersions field	`None`
`include`	`str \| JsonMatcher`	Matcher/expression to filter the query results (on client side). The inclusion is applied first. Creates a PyDF (Python Display Filter) matcher by default for strings.	`None`
`exclude`	`str \| JsonMatcher`	Matcher/expression to filter the query results (on client side). The exclusion is applied second. Creates a PyDF (Python Display Filter) matcher by default for strings.	`None`
`limit`	`int \| None`	Maximum number of results. Default is 5 to support quick Jupyter-style exploration; pass `None` to fetch all matching.	`5`
`page_size`	`int \| None`	Number of records read per request. If None (default), inferred from `limit` and whether client-side filters are set.	`None`
`page_number`	`int`	Pull a specific page; this effectively disables automatic follow-up page retrieval.	`None`
`as_values`	`*str\|tuple`	Don't parse objects, but directly extract the values at certain JSON paths as tuples.	`None`

Returns:

Type	Description
`AsyncIterator[Application]`	AsyncIterator of Application objects

`update(*applications: Application, workers: int | None = None) -> None` `async`

Update application objects within the database.

Parameters:

Name	Type	Description	Default
`*applications`	`Application`	Collection of Application instances	`()`
`workers`	`int`	The number of parallel processes to use	`None`

`upload_attachment(application_id: str, file: FileSpec) -> None` `async`

Upload application binary for a registered application.

Parameters:

Name	Type	Description	Default
`application_id`	`str`	The Cumulocity object ID of the application	required
`file`	`str \| PathLike \| BinaryIO`	File path or file-like object to upload.	required

See also: https://cumulocity.com/api/#tag/Application-binaries

`TenantOptions`

Provides access to the Tenant Options API.

This class can be used for get, search for, create, update and delete tenant options within the Cumulocity database.

See also: https://cumulocity.com/api/core/#tag/Options

`build_object_path(category: str, key: str) -> str`

Build the path to a specific tenant option.

Parameters:

Name	Type	Description	Default
`category`	`str`	Option category	required
`key`	`str`	Option key (name)	required

Returns:

Type	Description
`str`	The relative path to the option within Cumulocity.

`create(*options: TenantOption, workers: int | None = None) -> None` `async`

Create options within the database.

Parameters:

Name	Type	Description	Default
`*options`	`TenantOption`	Collection of TenantOption instances	`()`

`delete(*options: TenantOption, category: str | None = None, key: str | None = None, workers: int | None = None) -> None` `async`

Delete options within the database.

A single tenant option object can be deleted by specifying parameters category and 'key' directly. Alternatively, a collection of TenantOption objects can be created in a single call, optionally specifying the number of parallel worker threads.

Parameters:

Name	Type	Description	Default
`*options`	`TenantOption`	Collection of TenantOption instances	`()`
`category`	`str`	Option category	`None`
`key`	`str`	Option key (name)	`None`
`workers`	`int`	The number of parallel processes to use	`None`

`get(category: str, key: str) -> TenantOption` `async`

Retrieve a specific option from the database.

Note: The key must be prefixed with credentials. in order to retrieve an encrypted option.

Parameters:

Name	Type	Description	Default
`category`	`str`	Option category	required
`key`	`str`	Option key (name)	required

Returns:

Type	Description
`TenantOption`	A TenantOption instance

`get_all(expression: str | None = None, *, limit: int | None = 5, page_size: int | None = None, page_number: int | None = None, as_map: bool = False, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None) -> list[TenantOption] | dict[str, str] | dict[str, dict[str, str]]` `async`

Query the database for tenant options and return the results as list.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`limit`	`int`	Limit the number of results	`5`
`page_size`	`int`	Number of records read per request	`None`
`page_number`	`int`	Pull a specific page only	`None`
`as_map`	`bool`	Whether the categories should be returned as dict of keys and values (grouped by category if category is not specified). Defaults to False.	`False`
`as_values`	`str \| tuple \| Sequence[str \| tuple] \| None`	(str\|tuple\|list[str\|tuple]): Don't parse objects, but directly extract the values at certain JSON paths as tuples; If the path is not defined in a result, None is used; Specify a tuple to define a proper default value for each path.	`None`
`workers`	`int`	Number of parallel page-fetch workers	`None`

Returns:

Type	Description
`list[TenantOption] \| dict[str, str] \| dict[str, dict[str, str]]`	List of TenantOption instances or dictionary of key/value pairs
`list[TenantOption] \| dict[str, str] \| dict[str, dict[str, str]]`	grouped by category.

`get_value(category: str, key: str) -> str` `async`

Retrieve the value of a specific option from the database.

Note: The key must be prefixed with credentials. in order to retrieve an encrypted option.

Parameters:

Name	Type	Description	Default
`category`	`str`	Option category	required
`key`	`str`	Option key (name)	required

Returns:

Type	Description
`str`	The value of the specified option

`get_values(category: str) -> dict[str, str]` `async`

Retrieve all values for a specific category from the database.

Note: The keys of encrypted tenant options is automatically stripped from the credentials. prefix.

Parameters:

Name	Type	Description	Default
`category`	`str`	Option category	required

Returns:

Type	Description
`dict[str, str]`	The option values mapped by their key.

`select(expression: str | None = None, *, limit: int | None = 5, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None) -> AsyncIterator[TenantOption]`

Query the database for tenant options and iterate over the results.

When category is provided, a single targeted request is made instead of using standard pagination.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression which will be passed to Cumulocity without change; all other filters are ignored if this is provided	`None`
`limit`	`int \| None`	Maximum number of results. Default is 5 to support quick Jupyter-style exploration; pass `None` to fetch all matching.	`5`
`page_size`	`int \| None`	Number of records read per request. If None (default), inferred from `limit` and whether client-side filters are set.	`None`
`page_number`	`int`	Pull a specific page only	`None`
`as_values`	`str \| tuple \| Sequence[str \| tuple] \| None`	(str\|tuple\|list[str\|tuple]): Don't parse objects, but directly extract the values at certain JSON paths as tuples; If the path is not defined in a result, None is used; Specify a tuple to define a proper default value for each path.	`None`
`workers`	`int`	Number of parallel page-fetch workers	`None`

Returns:

Type	Description
`AsyncIterator[TenantOption]`	AsyncIterator of TenantOption objects or object values if
`AsyncIterator[TenantOption]`	as_values is specified,

`set_value(category: str, key: str, value: str) -> None` `async`

Create an option within the database.

Note: The key must be prefixed with credentials. in order to update an encrypted option.

Parameters:

Name	Type	Description	Default
`category`	`str`	Option category	required
`key`	`str`	Option key (name)	required
`value`	`str`	Option value	required

`update(*options: TenantOption, workers: int | None = None) -> None` `async`

Update options within the database.

Parameters:

Name	Type	Description	Default
`*options`	`TenantOption`	Collection of TenantOption instances	`()`
`workers`	`int`	Number of parallel workers	`None`

`update_values(category: str, values: dict[str, str]) -> None` `async`

Update existing option's values within the database.

Note: The key must be prefixed with credentials. in order to update an encrypted option.

Parameters:

Name	Type	Description	Default
`category`	`str`	Option category	required
`values`	`dict[str, str]`	Option values by key	required

`AuditRecords`

Provides access to the Audit API.

This class can be used for get, search for, and create audit records within the Cumulocity database.

See also: https://cumulocity.com/api/core/#tag/Audits

`create(*records: AuditRecord, workers: int | None = None) -> None` `async`

Create audit record objects within the database.

Parameters:

Name	Type	Description	Default
`*records`	`AuditRecord`	Collection of AuditRecord instances	`()`
`workers`	`int`	The number of parallel processes to use	`None`

`get(record_id: str) -> AuditRecord` `async`

Retrieve a specific audit record from the database.

Parameters:

Name	Type	Description	Default
`record_id`	`str`	The database ID of the audit record	required

Returns:

Type	Description
`AuditRecord`	An AuditRecord instance

get_all(expression: str | None = None, *, type: str | None = None, source: str | None = None, application: str | None = None, user: str | None = None, before: str | datetime | None = None, after: str | datetime | None = None, date_from: str | datetime | None = None, date_to: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, limit: int | None = 5, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None, **kwargs) -> list[AuditRecord] `async`

Query the database for audit records and return the results as list.

See select for a documentation of arguments.

Returns:

Type	Description
`list[AuditRecord]`	List of AuditRecord objects

`get_count(expression: str | None = None, *, type: str | None = None, source: str | None = None, application: str | None = None, user: str | None = None, before: str | datetime | None = None, after: str | datetime | None = None, date_from: str | datetime | None = None, date_to: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, **kwargs) -> int` `async`

Calculate the number of potential results of a database query.

This function uses the same parameters as the select function.

Returns:

Type	Description
`int`	Number of potential results

select(expression: str | None = None, *, type: str | None = None, source: str | None = None, application: str | None = None, user: str | None = None, before: str | datetime | None = None, after: str | datetime | None = None, date_from: str | datetime | None = None, date_to: str | datetime | None = None, min_age: str | timedelta | None = None, max_age: str | timedelta | None = None, include: str | JsonMatcher | None = None, exclude: str | JsonMatcher | None = None, limit: int | None = 5, page_size: int | None = None, page_number: int | None = None, as_values: str | tuple | Sequence[str | tuple] | None = None, workers: int | None = None, **kwargs) -> AsyncIterator[AuditRecord]

Query the database for audit records and iterate over the results.

This function is implemented in a lazy fashion - results will only be fetched from the database as long as there is a consumer for them.

Parameters:

Name	Type	Description	Default
`expression`	`str`	Arbitrary filter expression; all other filters are ignored if this is provided	`None`
`type`	`str`	Audit record type	`None`
`source`	`str`	Database ID of a source device	`None`
`application`	`str`	Application from which the audit was carried out	`None`
`user`	`str`	The user who carried out the activity	`None`
`before`	`str \| datetime`	Only records before this date	`None`
`after`	`str \| datetime`	Only records after this date	`None`
`date_from`	`str \| datetime`	Same as `after`	`None`
`date_to`	`str \| datetime`	Same as `before`	`None`
`min_age`	`timedelta \| str`	Minimum age for selected records	`None`
`max_age`	`timedelta \| str`	Maximum age for selected records	`None`
`include`	`str \| JsonMatcher`	Client-side inclusion filter	`None`
`exclude`	`str \| JsonMatcher`	Client-side exclusion filter	`None`
`limit`	`int \| None`	Maximum number of results. Default is 5 to support quick Jupyter-style exploration; pass `None` to fetch all matching.	`5`
`page_size`	`int \| None`	Number of records read per request. If None (default), inferred from `limit` and whether client-side filters are set.	`None`
`page_number`	`int`	Pull a specific page only	`None`
`as_values`	`str \| tuple \| Sequence[str \| tuple] \| None`	Extract values at JSON paths as tuples	`None`
`workers`	`int`	Number of parallel page-fetch workers	`None`

Returns:

Type	Description
`AsyncIterator[AuditRecord]`	AsyncIterator of AuditRecord objects

Main API Classes

Querying the database

Flexible query parameters

High-performance throughput

Object manipulation and bulk processing

Inventory

apply_to(model: dict | MO, *objects: str | MO, workers: int | None = None) -> None async

create(*objects: MO, workers: int | None = None) -> None async

delete(*objects: str | MO, workers: int | None = None) -> None async

get(id: str, *, with_children: bool | None = None, with_children_count: bool | None = None, skip_children_names: bool | None = None, with_parents: bool | None = None, with_latest_values: bool | None = None, **kwargs) -> MO async

get_latest_availability(mo_id: str) -> Availability async

get_supported_measurements(mo_id: str) -> list[str] async

get_supported_series(mo_id: str) -> list[str] async

update(*objects: MO, workers: int | None = None) -> None async

DeviceInventory

accept(id: str) async

delete(*devices: str | Device, workers: int | None = None) -> None async

request(id: str) async

Identity

__init__(c8y: CumulocityRestClient)

create(*objects: ExternalId, workers: int | None = None, external_id: str | None = None, external_type: str | None = None, managed_object_id: str | None = None) -> None async

delete(*objects: ExternalId, workers: int | None = None, external_id: str | None = None, external_type: str | None = None) -> None async

get(external_id: str, external_type: str) -> ExternalId async

get_all(object_id: str) -> list[ExternalId] async

get_id(external_id: str, external_type: str) -> str async

get_object(external_id: str, external_type: str) async

Binaries

create(*binaries: Binary, workers: int | None = None) -> int async

delete(*objects: str | Binary, workers: int | None = None) -> None async

get_count(expression: str | None = None, *, ids: Sequence[str] | None = None, type: str | None = None, owner: str | None = None, child_device: str | None = None, child_asset: str | None = None, child_addition: str | None = None, **kwargs) -> int async

read_file(id: str) -> bytes async

update(id: str, file: FileSpec, type: str | None = None) -> None async

upload(file: FileSpec, name: str, type: str) -> Binary async

Measurements

create(*objects: Measurement, workers: int | None = None) -> None async

delete(*objects: str | Measurement, workers: int | None = None) -> None async

get(id: str) -> Measurement async

Events

apply_to(model: dict | Event, *event_ids: str, workers: int | None = None) -> None async

build_attachment_path(event_id: str) -> str

create(*events: Event, workers: int | None = None) -> None async

create_attachment(event_id: str, file: FileSpec, content_type: str | None = None) -> dict async

delete(*events: str | Event, workers: int | None = None) -> None async

delete_attachment(event_id: str) -> None async

download_attachment(event_id: str) -> bytes async

get(event_id: str) -> Event async

update(*events: Event, workers: int | None = None) -> None async

update_attachment(event_id: str, file: FileSpec, content_type: str | None = None) -> dict async

Alarms

apply_to(alarm: Alarm | dict, *alarm_ids: str, workers: int | None = None) async

create(*alarms: Alarm, workers: int | None = None) -> None async

delete(*alarms: str | Alarm, workers: int | None = None) -> None async

get(id: str) -> Alarm async

update(*alarms: Alarm, workers: int | None = None) -> None async

Users

build_object_path(object_id: str) -> str

create(*users: User, workers: int | None = None) -> None async

delete(*users: str | User, workers: int | None = None) -> None async

get(username: str) async

get_count(expression: str | None = None, *, username: str | None = None, groups: str | int | UserGroup | Sequence[str | int | UserGroup] | None = None, owner: str | None = None, only_devices: bool | None = None) -> int async

get_current() -> CurrentUser async

get_tfa_settings(user_id: str) -> TfaSettings async

logout_all() async

revoke_totp_secret(user_id: str) async

set_current_password(current_password: str, new_password: str) async

set_delegate(user_id: str, delegate_id: str | None) async

set_owner(user_id: str, owner_id: str | None) async

update(*users: User, workers: int | None = None) -> None async

InventoryRoles

assign(username: str, managed_object_id: str | int, *roles: InventoryRole | int | str) -> InventoryRoleAssignment async

build_assignment_path(username: str, assignment_id: str | int | None = None) -> str

create(*roles: InventoryRole, workers: int | None = None) -> None async

delete(*roles: str | int | InventoryRole, workers: int | None = None) -> None async

get(role_id: int | str) -> InventoryRole async

get_assignments(username: str) -> list[InventoryRoleAssignment] async

reassign(username: str, assignment_id: str | int, managed_object_id: str | int, *roles: InventoryRole | int | str) -> InventoryRoleAssignment async

unassign(username: str, *assignment_ids: str | int, workers: int | None = None) -> None async

unassign_by(username: str, *objects: str | ManagedObject, workers: int | None = None) -> None async

update(*roles: InventoryRole, workers: int | None = None) -> None async

Subscriptions

`Inventory`

`apply_to(model: dict | MO, *objects: str | MO, workers: int | None = None) -> None` `async`

`create(*objects: MO, workers: int | None = None) -> None` `async`

`delete(*objects: str | MO, workers: int | None = None) -> None` `async`

`get(id: str, *, with_children: bool | None = None, with_children_count: bool | None = None, skip_children_names: bool | None = None, with_parents: bool | None = None, with_latest_values: bool | None = None, **kwargs) -> MO` `async`

`get_latest_availability(mo_id: str) -> Availability` `async`

`get_supported_measurements(mo_id: str) -> list[str]` `async`

`get_supported_series(mo_id: str) -> list[str]` `async`

`update(*objects: MO, workers: int | None = None) -> None` `async`

`DeviceInventory`

`accept(id: str)` `async`

`delete(*devices: str | Device, workers: int | None = None) -> None` `async`

`request(id: str)` `async`

`Identity`

`init(c8y: CumulocityRestClient)`

`create(*objects: ExternalId, workers: int | None = None, external_id: str | None = None, external_type: str | None = None, managed_object_id: str | None = None) -> None` `async`

`delete(*objects: ExternalId, workers: int | None = None, external_id: str | None = None, external_type: str | None = None) -> None` `async`

`get(external_id: str, external_type: str) -> ExternalId` `async`

`get_all(object_id: str) -> list[ExternalId]` `async`

`get_id(external_id: str, external_type: str) -> str` `async`

`get_object(external_id: str, external_type: str)` `async`

`Binaries`

`create(*binaries: Binary, workers: int | None = None) -> int` `async`

`delete(*objects: str | Binary, workers: int | None = None) -> None` `async`

`get_count(expression: str | None = None, *, ids: Sequence[str] | None = None, type: str | None = None, owner: str | None = None, child_device: str | None = None, child_asset: str | None = None, child_addition: str | None = None, **kwargs) -> int` `async`

`read_file(id: str) -> bytes` `async`

`update(id: str, file: FileSpec, type: str | None = None) -> None` `async`

`upload(file: FileSpec, name: str, type: str) -> Binary` `async`

`Measurements`

`create(*objects: Measurement, workers: int | None = None) -> None` `async`

`delete(*objects: str | Measurement, workers: int | None = None) -> None` `async`

`get(id: str) -> Measurement` `async`

`Events`

`apply_to(model: dict | Event, *event_ids: str, workers: int | None = None) -> None` `async`

`build_attachment_path(event_id: str) -> str`

`create(*events: Event, workers: int | None = None) -> None` `async`

`create_attachment(event_id: str, file: FileSpec, content_type: str | None = None) -> dict` `async`

`delete(*events: str | Event, workers: int | None = None) -> None` `async`

`delete_attachment(event_id: str) -> None` `async`

`download_attachment(event_id: str) -> bytes` `async`

`get(event_id: str) -> Event` `async`

`update(*events: Event, workers: int | None = None) -> None` `async`

`update_attachment(event_id: str, file: FileSpec, content_type: str | None = None) -> dict` `async`

`Alarms`

`apply_to(alarm: Alarm | dict, *alarm_ids: str, workers: int | None = None)` `async`

`create(*alarms: Alarm, workers: int | None = None) -> None` `async`

`delete(*alarms: str | Alarm, workers: int | None = None) -> None` `async`

`get(id: str) -> Alarm` `async`

`update(*alarms: Alarm, workers: int | None = None) -> None` `async`

`Users`

`build_object_path(object_id: str) -> str`

`create(*users: User, workers: int | None = None) -> None` `async`

`delete(*users: str | User, workers: int | None = None) -> None` `async`

`get(username: str)` `async`

`get_count(expression: str | None = None, *, username: str | None = None, groups: str | int | UserGroup | Sequence[str | int | UserGroup] | None = None, owner: str | None = None, only_devices: bool | None = None) -> int` `async`

`get_current() -> CurrentUser` `async`

`get_tfa_settings(user_id: str) -> TfaSettings` `async`

`logout_all()` `async`

`revoke_totp_secret(user_id: str)` `async`

`set_current_password(current_password: str, new_password: str)` `async`

`set_delegate(user_id: str, delegate_id: str | None)` `async`

`set_owner(user_id: str, owner_id: str | None)` `async`

`update(*users: User, workers: int | None = None) -> None` `async`

`InventoryRoles`

`assign(username: str, managed_object_id: str | int, *roles: InventoryRole | int | str) -> InventoryRoleAssignment` `async`

`build_assignment_path(username: str, assignment_id: str | int | None = None) -> str`

`create(*roles: InventoryRole, workers: int | None = None) -> None` `async`

`delete(*roles: str | int | InventoryRole, workers: int | None = None) -> None` `async`

`get(role_id: int | str) -> InventoryRole` `async`

`get_assignments(username: str) -> list[InventoryRoleAssignment]` `async`

`reassign(username: str, assignment_id: str | int, managed_object_id: str | int, *roles: InventoryRole | int | str) -> InventoryRoleAssignment` `async`

`unassign(username: str, *assignment_ids: str | int, workers: int | None = None) -> None` `async`

`unassign_by(username: str, *objects: str | ManagedObject, workers: int | None = None) -> None` `async`

`update(*roles: InventoryRole, workers: int | None = None) -> None` `async`

`Subscriptions`

`create(*subscriptions: Subscription, workers: int | None = None) -> None` `async`

`delete_by(expression: str | None = None, *, context: str | None = None, source: str | None = None) -> None` `async`

`get(subscription_id: str) -> Subscription` `async`

`get_count(expression: str | None = None, *, context: str | None = None, source: str | None = None, subscription: str | None = None, type_filter: str | None = None, **kwargs) -> int` `async`

`Tokens`