Account Module¶

This section documents the account components of the Nextmv Cloud API.

account ¶

Account management functionality for the Nextmv Cloud API.

This module provides classes for interacting with account-level resources in the Nextmv Platform, particularly for accessing and managing the queue of runs.

CLASS	DESCRIPTION
`QueuedRun`	A run that is pending to be executed in the account.
`Queue`	A list of runs that are pending or currently being executed.
`Account`	The Nextmv Platform account with API access methods.

Account ¶

Bases: BaseModel

The Nextmv Cloud account (organization).

To handle managed accounts, SSO must be configured for your organization. Please contact Nextmv support for assistance.

You can import the Account class directly from cloud:

python from nextmv.cloud import Account

This class provides access to account-level operations in the Nextmv Cloud, such as retrieving the queue of runs.

Note: It is recommended to use Account.get() or Account.new() instead of direct initialization to ensure proper setup.

Attributes¶

account_id : str, optional ID of the account (organization). name : str, optional Name of the account (organization). members : list[AccountMember], optional List of members in the account (organization). client : Client Client to use for interacting with the Nextmv Cloud API. This is an SDK-specific attribute and it is not part of the API representation of an account. account_endpoint : str, default="v1/account" Base endpoint for the account. This is an SDK-specific attribute and it is not part of the API representation of an account. organization_endpoint : str, default="v1/organization/{organization_id}" Base endpoint for organization operations. This is an SDK-specific attribute and it is not part of the API representation of an account.

Examples¶

from nextmv.cloud import Client, Account client = Client(api_key="your-api-key")

Retrieve an existing account¶

account = Account.get(client=client, account_id="your-account-id") print(f"Account name: {account.name}") Account name: Bunny Logistics

Create a new account¶

new_account = Account.new(client=client, name="Hare Delivery Co", admins=["admin@example.com"])

Get the queue of runs¶

queue = account.queue() print(f"Number of runs in queue: {len(queue.runs)}") Number of runs in queue: 3

Returned by:

nextmv ☁️ Cloud Reference Account Module account Account
- get
- new
- update

account_endpoint `class-attribute` `instance-attribute` ¶

account_endpoint: str = Field(
    exclude=True, default="v1/account"
)

Base endpoint for the account.

account_id `class-attribute` `instance-attribute` ¶

account_id: str | None = Field(
    serialization_alias="id",
    validation_alias=AliasChoices("id", "account_id"),
    default=None,
)

ID of the account (organization).

client `class-attribute` `instance-attribute` ¶

client: Client = Field(exclude=True)

Client to use for interacting with the Nextmv Cloud API.

delete ¶

delete() -> None

Delete the account.

Permanently removes the account (organization) from Nextmv Cloud. You must have the administrator role on that account in order to delete it.

RAISES	DESCRIPTION
`HTTPError`	If the response status code is not 2xx.

Examples:

>>> account.delete()  # Permanently deletes the account

Source code in nextmv/nextmv/cloud/account.py

def delete(self) -> None:
    """
    Delete the account.

    Permanently removes the account (organization) from Nextmv Cloud. You
    must have the administrator role on that account in order to delete it.

    Raises
    ------
    requests.HTTPError
        If the response status code is not 2xx.

    Examples
    --------
    >>> account.delete()  # Permanently deletes the account
    """

    _ = self.client.request(
        method="DELETE",
        endpoint=self.organization_endpoint,
    )

get `classmethod` ¶

get(client: Client, account_id: str) -> Account

Retrieve an account directly from Nextmv Cloud.

This function is useful if you want to populate an Account class by fetching the attributes directly from Nextmv Cloud.

PARAMETER	DESCRIPTION
`client` ¶	Client to use for interacting with the Nextmv Cloud API. TYPE: `Client`
`account_id` ¶	ID of the account to retrieve. TYPE: `str`

RETURNS	DESCRIPTION
`Account`	The requested account.

RAISES	DESCRIPTION
`HTTPError`	If the response status code is not 2xx.

Examples:

>>> from nextmv.cloud import Client, Account
>>> client = Client(api_key="your-api-key")
>>> account = Account.get(client=client, account_id="bunny-logistics")
>>> print(f"Account: {account.name}")
Account: Bunny Logistics
>>> print(f"Members: {len(account.members)}")
Members: 3

Source code in nextmv/nextmv/cloud/account.py

@classmethod
def get(cls, client: Client, account_id: str) -> "Account":
    """
    Retrieve an account directly from Nextmv Cloud.

    This function is useful if you want to populate an `Account` class
    by fetching the attributes directly from Nextmv Cloud.

    Parameters
    ----------
    client : Client
        Client to use for interacting with the Nextmv Cloud API.
    account_id : str
        ID of the account to retrieve.

    Returns
    -------
    Account
        The requested account.

    Raises
    ------
    requests.HTTPError
        If the response status code is not 2xx.

    Examples
    --------
    >>> from nextmv.cloud import Client, Account
    >>> client = Client(api_key="your-api-key")
    >>> account = Account.get(client=client, account_id="bunny-logistics")
    >>> print(f"Account: {account.name}")
    Account: Bunny Logistics
    >>> print(f"Members: {len(account.members)}")
    Members: 3
    """

    response = client.request(
        method="GET",
        endpoint=f"v1/organization/{account_id}",
    )

    return cls.from_dict({"client": client} | response.json())

members `class-attribute` `instance-attribute` ¶

members: list[AccountMember] | None = None

List of members in the account (organization).

model_post_init ¶

model_post_init(__context) -> None

Initialize the organization_endpoint attribute.

This method is automatically called after class initialization to format the organization_endpoint URL with the account ID.

Source code in nextmv/nextmv/cloud/account.py

def model_post_init(self, __context) -> None:
    """
    Initialize the organization_endpoint attribute.

    This method is automatically called after class initialization to
    format the organization_endpoint URL with the account ID.
    """

    self.organization_endpoint = self.organization_endpoint.format(organization_id=self.account_id)

name `class-attribute` `instance-attribute` ¶

name: str | None = None

Name of the account (organization).

new `classmethod` ¶

new(
    client: Client, name: str, admins: list[str]
) -> Account

Create a new account (organization) directly in Nextmv Cloud.

To create managed accounts, SSO must be configured for your organization. Please contact Nextmv support for assistance.

PARAMETER	DESCRIPTION
`client` ¶	Client to use for interacting with the Nextmv Cloud API. TYPE: `Client`
`name` ¶	Name of the new account. TYPE: `str`
`admins` ¶	List of admin user emails for the new account. TYPE: `list[str]`

RETURNS	DESCRIPTION
`Account`	The newly created account.

Examples:

>>> from nextmv.cloud import Client
>>> client = Client(api_key="your-api-key")
>>> account = Account.new(client=client, name="My New Account", admins=["admin@example.com"])

Source code in nextmv/nextmv/cloud/account.py

@classmethod
def new(
    cls,
    client: Client,
    name: str,
    admins: list[str],
) -> "Account":
    """
    Create a new account (organization) directly in Nextmv Cloud.

    To create managed accounts, SSO must be configured for your
    organization. Please contact [Nextmv
    support](https://www.nextmv.io/contact) for assistance.

    Parameters
    ----------
    client : Client
        Client to use for interacting with the Nextmv Cloud API.
    name : str
        Name of the new account.
    admins : list[str]
        List of admin user emails for the new account.

    Returns
    -------
    Account
        The newly created account.

    Examples
    --------
    >>> from nextmv.cloud import Client
    >>> client = Client(api_key="your-api-key")
    >>> account = Account.new(client=client, name="My New Account", admins=["admin@example.com"])
    """

    if len(admins) == 0:
        raise ValueError("at least one admin email must be provided to create an account")

    payload = {
        "name": name,
        "admins": admins,
    }

    response = client.request(
        method="POST",
        endpoint="v1/organization",
        payload=payload,
    )

    return cls.from_dict({"client": client} | response.json())

organization_endpoint `class-attribute` `instance-attribute` ¶

organization_endpoint: str = Field(
    exclude=True,
    default="v1/organization/{organization_id}",
)

queue ¶

queue() -> Queue

Warning

Account.queue is deprecated, use Application.list_runs with status=StatusV2.queued instead.

Get the queue of runs in the account.

Retrieves the current list of runs that are pending or being executed in the Nextmv account.

RETURNS	DESCRIPTION
`Queue`	Queue of runs in the account.

RAISES	DESCRIPTION
`HTTPError`	If the response status code is not 2xx.

Examples:

>>> from nextmv.cloud import Client, Account
>>> client = Client(api_key="your-api-key")
>>> account = Account.get(client=client, account_id="your-account-id")
>>> queue = account.queue()
>>> for run in queue.runs:
...     print(f"Run {run.id}: {run.name} - Status: {run.status_v2}")
Run run-123: Daily Optimization - Status: RUNNING
Run run-456: Weekly Planning - Status: QUEUED

Source code in nextmv/nextmv/cloud/account.py

def queue(self) -> Queue:
    """
    !!! warning
        `Account.queue` is deprecated, use `Application.list_runs` with `status=StatusV2.queued` instead.

    Get the queue of runs in the account.

    Retrieves the current list of runs that are pending or being executed
    in the Nextmv account.

    Returns
    -------
    Queue
        Queue of runs in the account.

    Raises
    ------
    requests.HTTPError
        If the response status code is not 2xx.

    Examples
    --------
    >>> from nextmv.cloud import Client, Account
    >>> client = Client(api_key="your-api-key")
    >>> account = Account.get(client=client, account_id="your-account-id")
    >>> queue = account.queue()
    >>> for run in queue.runs:
    ...     print(f"Run {run.id}: {run.name} - Status: {run.status_v2}")
    Run run-123: Daily Optimization - Status: RUNNING
    Run run-456: Weekly Planning - Status: QUEUED
    """
    deprecated(
        name="Account.queue",
        reason="`Account.queue` is deprecated, use `Application.list_runs` with `status=StatusV2.queued` instead",
    )

    response = self.client.request(
        method="GET",
        endpoint=self.account_endpoint + "/queue",
    )

    return Queue.from_dict(response.json())

update ¶

update(name: str) -> Account

Update the account.

PARAMETER	DESCRIPTION
`name` ¶	Name of the account. TYPE: `str`

RETURNS	DESCRIPTION
`Account`	The updated account.

RAISES	DESCRIPTION
`HTTPError`	If the response status code is not 2xx.

Examples:

>>> from nextmv.cloud import Client, Account
>>> client = Client(api_key="your-api-key")
>>> account = Account.get(client=client, account_id="bunny-logistics")
>>> updated_account = account.update(name="Bunny Express Logistics")
>>> print(updated_account.name)
Bunny Express Logistics

Source code in nextmv/nextmv/cloud/account.py

def update(self, name: str) -> "Account":
    """
    Update the account.

    Parameters
    ----------
    name : str
        Name of the account.

    Returns
    -------
    Account
        The updated account.

    Raises
    ------
    requests.HTTPError
        If the response status code is not 2xx.

    Examples
    --------
    >>> from nextmv.cloud import Client, Account
    >>> client = Client(api_key="your-api-key")
    >>> account = Account.get(client=client, account_id="bunny-logistics")
    >>> updated_account = account.update(name="Bunny Express Logistics")
    >>> print(updated_account.name)
    Bunny Express Logistics
    """

    account = self.get(client=self.client, account_id=self.account_id)
    account_dict = account.to_dict()
    payload = account_dict.copy()
    payload["name"] = name

    response = self.client.request(
        method="PUT",
        endpoint=self.organization_endpoint,
        payload=payload,
    )

    return Account.from_dict({"client": self.client} | response.json())

AccountMember ¶

Bases: BaseModel

A member of a Nextmv Cloud account (organization).

You can import the AccountMember class directly from cloud:

from nextmv.cloud import AccountMember

Represents an individual member of an organization in Nextmv Cloud, including their role and invitation status.

ATTRIBUTE	DESCRIPTION
`email`	Email of the account member. TYPE: `str \| None`
`role`	Role of the account member. TYPE: `str \| None`
`pending_invite`	Whether the member has a pending invite. TYPE: `bool \| None`

Examples:

>>> member = AccountMember.from_dict({
...     "email": "peter.rabbit@carrotexpress.com",
...     "role": "admin",
...     "pending_invite": False
... })
>>> print(f"{member.email} - {member.role}")
peter.rabbit@carrotexpress.com - admin

Returned by:

nextmv ☁️ Cloud Reference Account Module account Account members

email `class-attribute` `instance-attribute` ¶

email: str | None = None

Email of the account member.

pending_invite `class-attribute` `instance-attribute` ¶

pending_invite: bool | None = None

Whether the member has a pending invite.

role `class-attribute` `instance-attribute` ¶

role: str | None = None

Role of the account member.

Queue ¶

Bases: BaseModel

A queue is a list of runs that are pending to be executed, or currently being executed, in the account.

You can import the Queue class directly from cloud:

from nextmv.cloud import Queue

The Queue object provides access to a list of queued runs in a Nextmv account. It is typically obtained through the Account.queue() method.

ATTRIBUTE	DESCRIPTION
`runs`	List of runs in the queue. TYPE: `list[QueuedRun]`

Examples:

>>> from nextmv.cloud import Client, Account
>>> client = Client(api_key="your-api-key")
>>> account = Account.get(client=client, account_id="your-account-id")
>>> queue = account.queue()
>>> print(f"Number of runs in queue: {len(queue.runs)}")
Number of runs in queue: 5
>>> # Accessing the first run in the queue
>>> if queue.runs:
...     print(f"First run: {queue.runs[0].name}")
First run: My Priority Run

Returned by:

nextmv ☁️ Cloud Reference Account Module account Account queue

runs `instance-attribute` ¶

runs: list[QueuedRun]

List of runs in the queue.

QueuedRun ¶

Bases: BaseModel

A run that is pending to be executed in the account.

You can import the QueuedRun class directly from cloud:

from nextmv.cloud import QueuedRun

Represents details of a run in the queue, including its status and metadata. QueuedRun objects are typically obtained through the Account.queue() method.

ATTRIBUTE	DESCRIPTION
`id`	ID of the run. TYPE: `str`
`user_email`	Email of the user who created the run. TYPE: `str`
`name`	Name of the run. TYPE: `str`
`description`	Description of the run. TYPE: `str`
`created_at`	Creation date of the run. TYPE: `datetime`
`application_id`	ID of the application used for the run. TYPE: `str`
`application_instance_id`	ID of the application instance used for the run. TYPE: `str`
`application_version_id`	ID of the application version used for the run. TYPE: `str`
`execution_class`	Execution class used for the run. TYPE: `str`
`status_v2`	Status of the run. TYPE: `StatusV2`

Examples:

>>> queued_run = QueuedRun.from_dict({
...     "id": "run-123456",
...     "user_email": "user@example.com",
...     "name": "My Run",
...     "description": "Test run",
...     "created_at": "2023-01-01T12:00:00Z",
...     "application_id": "app-123456",
...     "application_instance_id": "appins-123456",
...     "application_version_id": "appver-123456",
...     "execution_class": "standard",
...     "status_v2": "RUNNING"
... })
>>> print(queued_run.name)
My Run

Returned by:

nextmv ☁️ Cloud Reference Account Module account Queue runs

application_id `instance-attribute` ¶

application_id: str

ID of the application used for the run.

application_instance_id `instance-attribute` ¶

application_instance_id: str

ID of the application instance used for the run.

application_version_id `instance-attribute` ¶

application_version_id: str

ID of the application version used for the run.

created_at `instance-attribute` ¶

created_at: datetime

Creation date of the run.

description `instance-attribute` ¶

description: str

Description of the run.

execution_class `instance-attribute` ¶

execution_class: str

Execution class used for the run.

id `instance-attribute` ¶

id: str

ID of the run.

name `instance-attribute` ¶

name: str

Name of the run.

status_v2 `instance-attribute` ¶

status_v2: StatusV2

Status of the run.

user_email `instance-attribute` ¶

user_email: str

Email of the user who created the run.

Account Module¶

account ¶

Account ¶

Attributes¶

Examples¶

Retrieve an existing account¶

Create a new account¶

Get the queue of runs¶

account_endpoint class-attribute instance-attribute ¶

account_id class-attribute instance-attribute ¶

client class-attribute instance-attribute ¶

delete ¶

get classmethod ¶

client ¶

account_id ¶

members class-attribute instance-attribute ¶

model_post_init ¶

name class-attribute instance-attribute ¶

new classmethod ¶

client ¶

name ¶

admins ¶

organization_endpoint class-attribute instance-attribute ¶

queue ¶

update ¶

name ¶

AccountMember ¶

email class-attribute instance-attribute ¶

pending_invite class-attribute instance-attribute ¶

role class-attribute instance-attribute ¶

Queue ¶

runs instance-attribute ¶

QueuedRun ¶

application_id instance-attribute ¶

application_instance_id instance-attribute ¶

application_version_id instance-attribute ¶

created_at instance-attribute ¶

description instance-attribute ¶

execution_class instance-attribute ¶

id instance-attribute ¶

name instance-attribute ¶

status_v2 instance-attribute ¶

user_email instance-attribute ¶

account_endpoint `class-attribute` `instance-attribute` ¶

account_id `class-attribute` `instance-attribute` ¶

client `class-attribute` `instance-attribute` ¶

get `classmethod` ¶

`client` ¶

`account_id` ¶

members `class-attribute` `instance-attribute` ¶

name `class-attribute` `instance-attribute` ¶

new `classmethod` ¶

`client` ¶

`name` ¶

`admins` ¶

organization_endpoint `class-attribute` `instance-attribute` ¶

`name` ¶

email `class-attribute` `instance-attribute` ¶

pending_invite `class-attribute` `instance-attribute` ¶

role `class-attribute` `instance-attribute` ¶

runs `instance-attribute` ¶

application_id `instance-attribute` ¶

application_instance_id `instance-attribute` ¶

application_version_id `instance-attribute` ¶

created_at `instance-attribute` ¶

description `instance-attribute` ¶

execution_class `instance-attribute` ¶

id `instance-attribute` ¶

name `instance-attribute` ¶

status_v2 `instance-attribute` ¶

user_email `instance-attribute` ¶