Personalization

albert.collections.personalization.PersonalizationCollection

PersonalizationCollection(*, session: AlbertSession)

Bases: BaseCollection

Manage user personalization records in the Albert platform.

Personalization records store per-user preferences such as starred projects, hidden rows, and saved filters. Records always belong to a user: records created or listed without an explicit user belong to the current user.

This collection is accessed as client.personalization.

Example

from albert import Albert
from albert.resources.personalization import Personalization, PersonalizationCategory

client = Albert()
record = client.personalization.create(
    personalization=Personalization(
        category=PersonalizationCategory.STARRED_PROJECTS,
        saved_id="PRO123",
        saved_name="Weatherproof Coatings 2026",
    )
)
print(record.id)

Parameters:

Name	Type	Description	Default
session	AlbertSession	The authenticated Albert session used for API calls.	required

Attributes:

Name	Type	Description
base_path	str	The base API route for personalization requests.

Methods:

Name	Description
create	Create a new personalization record for the current user.
get_by_id	Get a single personalization record by its ID.
get_all	Get personalization records, with optional filters.
delete	Delete a personalization record by its ID.

Source code in src/albert/collections/personalization.py

def __init__(self, *, session: AlbertSession):
    super().__init__(session=session)
    self.base_path = f"/api/{PersonalizationCollection._api_version}/personalization"

base_path

base_path = f"/api/{PersonalizationCollection._api_version}/personalization"

create

create(
    *, personalization: Personalization
) -> Personalization

Create a new personalization record for the current user.

Example

from albert.resources.personalization import Personalization, PersonalizationCategory

record = client.personalization.create(
    personalization=Personalization(
        category=PersonalizationCategory.STARRED_PROJECTS,
        saved_id="PRO123",
        saved_name="Weatherproof Coatings 2026",
    )
)
record.id
# 'USP123'

Parameters:

Name	Type	Description	Default
personalization	Personalization	The record to create. Requires category plus the fields the category stores (e.g. saved_id and saved_name for a starred project).	required

Returns:

Type	Description
Personalization	The created record, populated with its assigned ID.

Source code in src/albert/collections/personalization.py

@validate_call
def create(self, *, personalization: Personalization) -> Personalization:
    """Create a new personalization record for the current user.

    !!! example
        ```python
        from albert.resources.personalization import Personalization, PersonalizationCategory

        record = client.personalization.create(
            personalization=Personalization(
                category=PersonalizationCategory.STARRED_PROJECTS,
                saved_id="PRO123",
                saved_name="Weatherproof Coatings 2026",
            )
        )
        record.id
        # 'USP123'
        ```

    Parameters
    ----------
    personalization : Personalization
        The record to create. Requires ``category`` plus the fields the
        category stores (e.g. ``saved_id`` and ``saved_name`` for a starred
        project).

    Returns
    -------
    Personalization
        The created record, populated with its assigned ID.
    """
    payload = personalization.model_dump(
        by_alias=True, exclude_none=True, exclude_unset=True, mode="json"
    )
    response = self.session.post(self.base_path, json=[payload])
    data = response.json()[0]
    # The create response omits `category`; the value just sent is authoritative.
    data.setdefault("category", payload["category"])
    return Personalization(**data)

get_by_id

get_by_id(*, id: str) -> Personalization

Get a personalization record by its ID.

Example

record = client.personalization.get_by_id(id="USP123")
record.category
# <PersonalizationCategory.STARRED_PROJECTS: 'Starred Projects'>

Parameters:

Name	Type	Description	Default
id	str	The ID of the record to retrieve (format USP...).	required

Returns:

Type	Description
Personalization	The fully populated record.

Source code in src/albert/collections/personalization.py

@validate_call
def get_by_id(self, *, id: str) -> Personalization:
    """Get a personalization record by its ID.

    !!! example
        ```python
        record = client.personalization.get_by_id(id="USP123")
        record.category
        # <PersonalizationCategory.STARRED_PROJECTS: 'Starred Projects'>
        ```

    Parameters
    ----------
    id : str
        The ID of the record to retrieve (format ``USP...``).

    Returns
    -------
    Personalization
        The fully populated record.
    """
    response = self.session.get(f"{self.base_path}/{id}")
    return Personalization(**response.json())

get_all

get_all(
    *,
    category: PersonalizationCategory | None = None,
    sub_category: str | None = None,
    user_id: str | None = None,
    max_items: int | None = None,
) -> Iterator[Personalization]

Get personalization records, with optional filters.

When user_id is not given, records of the current user are returned.

Example

from albert.resources.personalization import PersonalizationCategory

for record in client.personalization.get_all(
    category=PersonalizationCategory.STARRED_PROJECTS
):
    print(record.id, record.saved_id)

Parameters:

Name	Type	Description	Default
category	PersonalizationCategory	Only return records in this category.	None
sub_category	str	Only return records in this subcategory. Requires category.	None
user_id	str	Only return records belonging to this user. Defaults to the current user.	None
max_items	int	Maximum number of records to return in total. If None, returns all matching records.	None

Returns:

Type	Description
Iterator[Personalization]	An iterator of matching records.

Raises:

Type	Description
ValueError	If sub_category is given without category.

Source code in src/albert/collections/personalization.py

@validate_call
def get_all(
    self,
    *,
    category: PersonalizationCategory | None = None,
    sub_category: str | None = None,
    user_id: str | None = None,
    max_items: int | None = None,
) -> Iterator[Personalization]:
    """Get personalization records, with optional filters.

    When ``user_id`` is not given, records of the current user are returned.

    !!! example
        ```python
        from albert.resources.personalization import PersonalizationCategory

        for record in client.personalization.get_all(
            category=PersonalizationCategory.STARRED_PROJECTS
        ):
            print(record.id, record.saved_id)
        ```

    Parameters
    ----------
    category : PersonalizationCategory, optional
        Only return records in this category.
    sub_category : str, optional
        Only return records in this subcategory. Requires ``category``.
    user_id : str, optional
        Only return records belonging to this user. Defaults to the current
        user.
    max_items : int, optional
        Maximum number of records to return in total. If None, returns all
        matching records.

    Returns
    -------
    Iterator[Personalization]
        An iterator of matching records.

    Raises
    ------
    ValueError
        If ``sub_category`` is given without ``category``.
    """
    params = self._get_all_params(
        category=category, sub_category=sub_category, user_id=user_id
    )
    if "createdBy" not in params:
        params["createdBy"] = UserCollection(session=self.session).get_current_user().id
    return AlbertPaginator(
        mode=PaginationMode.KEY,
        path=self.base_path,
        session=self.session,
        params=params,
        max_items=max_items,
        deserialize=lambda items: [Personalization(**item) for item in items],
    )

delete

delete(*, id: str) -> None

Delete a personalization record by its ID.

Example

client.personalization.delete(id="USP123")

Parameters:

Name	Type	Description	Default
id	str	The ID of the record to delete (format USP...).	required

Returns:

Type	Description
None

Source code in src/albert/collections/personalization.py

@validate_call
def delete(self, *, id: str) -> None:
    """Delete a personalization record by its ID.

    !!! example
        ```python
        client.personalization.delete(id="USP123")
        ```

    Parameters
    ----------
    id : str
        The ID of the record to delete (format ``USP...``).

    Returns
    -------
    None
    """
    self.session.delete(f"{self.base_path}/{id}")