air_sdk.endpoints.history

Classes

Name	Description
`History`	A history entry from the legacy flat `histories` endpoint.
`HistoryModelMixin`	Nested history reads for a resource (`history` + `history-filters`).
`HistoryEndpointAPI`	API for querying simulation and node history entries (legacy flat endpoint).

Module Contents

class air_sdk.endpoints.history.History

Bases: air_sdk.air_model.AirModel

A history entry from the legacy flat histories endpoint.

Returned by api.histories.list() and the deprecated Simulation.get_history(). Entries are immutable and read-only. For per-resource history, prefer the nested list_history() (see HistoryModelMixin), which yields HistoryEntry.

History entries cannot be created, updated, or deleted via the SDK. They are automatically generated by the Air API.

object_id: str

ID of the entity this history entry is about (e.g., a simulation ID)

model: str

Type of entity being tracked (e.g., ‘simulation’)

created: datetime.datetime

Timestamp when the history entry was created

actor: str

Email or identifier of the user who performed the action

description: str

Human-readable description of what happened

category: str

Category of the event. Values: ‘INFO’, ‘ERROR’

get_model_api() -> type[HistoryEndpointAPI]

Returns the respective AirModelAPI type for this model

refresh() -> None

Refresh the history entry.

History entries are read-only and created automatically by the Air API. They cannot be modified or refreshed.

Raises:

NotImplementedError – History entries are immutable and cannot be refreshed

class air_sdk.endpoints.history.HistoryModelMixin

Nested history reads for a resource (history + history-filters).

Provides the list_history() and get_history_filters() convenience methods on resources that support per-resource history (Simulation, Node, Image, MarketplaceDemo). These read the resource’s own nested history endpoints rather than the legacy flat histories endpoint.

list_history(
    *,
    severity: str = ...,
    actor: str = ...,
    label: str = ...,
    search: str = ...,
    ordering: Literal[list_history.actor, list_history.severity, created, -actor, -severity, -created] = ...,
    limit: int = ...,
    offset: int = ...
) -> Iterator[HistoryEntry]

List the history entries for this resource.

Reads the resource’s nested history endpoint and yields read-only HistoryEntry dicts (newest-first by default).

Parameters:

severity – Filter by event severity. Values: ‘INFO’, ‘ERROR’
actor – Filter by the actor who performed the action (case-insensitive)
label – Only return entries carrying this label (e.g., ‘publishing’)
search – Search for a substring across actor, description, severity, and labels
ordering – Order by field. Prefix with ’-’ for descending order (e.g., ‘-created’)
limit – Maximum number of results to return per page
offset – Number of results to skip (for pagination)

Returns:

Iterator of HistoryEntry dicts for this resource

Example:

>>> for entry in simulation.list_history(ordering='-created'):
...     print(f'{entry["created"]}: {entry["description"]}')
>>> # Only publishing-lifecycle entries for an image:
>>> for entry in image.list_history(label='publishing'):
...     print(entry['description'])

get_history_filters() -> HistoryFilters

Get the distinct history filter values for this resource.

Returns the distinct actors, severities, and labels present across all of this resource’s history entries - the values that populate a filter UI. The options are the same for every caller allowed to read the history.

Returns:

A HistoryFilters mapping with ‘actors’, ‘severities’, and ‘labels’ lists.

Example:

>>> filters = image.get_history_filters()
>>> print(filters['actors'])
>>> print(filters['labels'])

class air_sdk.endpoints.history.HistoryEndpointAPI

Bases: air_sdk.endpoints.mixins.ListApiMixin[air_sdk.endpoints.history.History], air_sdk.air_model.BaseEndpointAPI[air_sdk.endpoints.history.History]

API for querying simulation and node history entries (legacy flat endpoint).

History entries are read-only records of actions and events for Air resources.

This flat endpoint serves simulation and node history. For image and marketplace-demo history - and as the preferred path for simulations - use the nested list_history() / get_history_filters() methods on the resource (see HistoryModelMixin).

This endpoint only supports list() operations. History entries cannot be created, updated, or deleted via the API.

API_PATH: str

model: type[History]

list(
    *,
    model: Literal[simulation, node] = ...,
    object_id: str | None = ...,
    actor: str | None = ...,
    category: str | None = ...,
    search: str | None = ...,
    ordering: str | None = ...,
    limit: int | None = ...,
    offset: int | None = ...
) -> Iterator[History]

List simulation and node history entries, with optional filtering and paging.

Parameters:

model – Entity type to get history for. Accepts ‘simulation’ or ‘node’ on this legacy endpoint; image and marketplace-demo history are served by the nested resource endpoints.
object_id – Filter by the ID of the entity being tracked (e.g., a specific simulation’s ID)
actor – Filter by actor email or identifier
category – Filter by event category. Values: ‘INFO’, ‘ERROR’
search – Search for substrings in actor or description fields
ordering – Order by field (prefix with ’-’ for descending). Available fields: actor, category, created, model, object_id
limit – Maximum number of results to return per page
offset – Number of results to skip (for pagination)

Yields:

History instances

Example:

>>> # List all simulation history
>>> for entry in api.histories.list(model='simulation'):
...     print(entry.description)
>>>
>>> # Get history for a specific simulation
>>> for entry in api.histories.list(
...     model='simulation',
...     object_id='3dadd54d-583c-432e-9383-a2b0b1d7f551'
... ):
...     print(f'{entry.created}: {entry.description}')
>>>
>>> # Filter by category
>>> errors = list(api.histories.list(model='simulation', category='ERROR'))
>>> print(f'Found {len(errors)} errors')
>>>
>>> # Order by creation time (newest first)
>>> for entry in api.histories.list(
...     model='simulation',
...     ordering='-created',
...     limit=5
... ):
...     print(f'{entry.created}: {entry.description}')