Retrieve

Retrieve one or more meters by id.

Retrieves consumption data by meterId. Pass a single string to get one meter, or a list of strings to get multiple meters at once.

Parameters:

id (str | SequenceNotStr[str]) – Single meter ID or list of meter IDs. Metering is identified by an id containing the service name and a service-scoped metering name. For instance atlas.monthly_ai_tokens is the id of the atlas service metering monthly_ai_tokens. Service and metering names are always in lower_snake_case.
start (int | str | datetime.datetime | None) – Start of the time range for historical data. Accepts milliseconds since epoch, a datetime object, or a relative time string like "2w-ago". Must be provided together with number_of_datapoints to get time-series data. If omitted, only meter metadata is returned without time-series data.
end (int | str | datetime.datetime | None) – End of the time range for historical data. Accepts milliseconds since epoch, a datetime object, or a relative time string like "now". Only relevant when start is provided. Defaults to the current time on the server if omitted.
number_of_datapoints (int | None) – Number of equal-width time buckets to return between start and end. Must be provided together with start to get time-series data. Valid range: 0-600. API server default is 0 (metadata only).

Returns:

If a single ID is given: the requested meter, or None if not found. If a list of IDs is given: the requested meters in the same order.

Return type:

MeteringData | MeteringDataList | None

Examples

Retrieve a single meter by id:

>>> from cognite.client import CogniteClient, AsyncCogniteClient
>>> client = CogniteClient()
>>> # async_client = AsyncCogniteClient()  # another option
>>> res = client.metering.retrieve(id="atlas.monthly_ai_tokens")

Retrieve multiple meters by id:

>>> res = client.metering.retrieve(id=["atlas.monthly_ai_tokens", "files.storage_bytes"])

Retrieve a single meter with historical data:

>>> res = client.metering.retrieve(
...     id="atlas.monthly_ai_tokens",
...     start=1764547200000,
...     end=1767225599000,
...     number_of_datapoints=30,
... )