Enterprise Management SDK#

One of FiftyOne’s core design principles is that you should be able to do everything programmatically if you want.

To this end, the fiftyone.management module provides Enterprise-specific methods for managing users, invitations, dataset permissions, plugins, API keys, and more.

Note

You must use an API connection (not a direct MongoDB connection) in order to use Management SDK methods.

API reference#

Connections#

API connection.

Copyright 2017-2025, Voxel51, Inc.
voxel51.com

Functions:

`reload_api_connection`()	Reloads the API connection.
`test_api_connection`()	Tests the API connection.

fiftyone.management.connection.reload_api_connection() → None#

Reloads the API connection.

This is necessary if the API URI or API key are changed after the first usage of this module.

Note

This should rarely be needed unless a script is working across deployments.

Examples:

import fiftyone.management as fom
import fiftyone as fo

# https://api.dev.mycompany.org
print(fo.config.api_uri)
fom.whoami()

# Change API URI, need to reload cached connection
fo.config.api_uri = "https://api.test.mycompany.org"
fom.reload_api_connection()
fom.whoami()

fiftyone.management.connection.test_api_connection()#

Tests the API connection.

If the connection succeeds, a message will be printed. If the connection failes, an exception will be raised.

Examples:

import fiftyone.management as fom
fom.test_api_connection() # API connection succeeded

API keys#

API key management.

Copyright 2017-2025, Voxel51, Inc.
voxel51.com

Classes:

APIKey(id, name, created_at)

API key dataclass.

Functions:

`delete_api_key`(key[, user])	Deletes the API key for the given user (default: current user).
`generate_api_key`(key_name[, user])	Generates an API key for the given user (default: current user).
`list_api_keys`([user])	Lists all API keys for the given user (default: current user).

class fiftyone.management.api_key.APIKey(id: str, name: str, created_at: datetime)#

API key dataclass.

Attributes:

`id`
`name`
`created_at`

id: str#

name: str#

created_at: datetime#

fiftyone.management.api_key.delete_api_key(key: str, user: str | User | None = None) → None#

Deletes the API key for the given user (default: current user).

Note

Only admins can delete keys for other users.

Examples:

import fiftyone.management as fom

# Delete all keys from a user
email = "user@company.com"
for key in fom.list_api_keys(email):
    fom.delete_api_key(key.id, email)

Parameters:

key – the ID of the key to delete
user (None) – an optional user ID, email string, or User instance. Defaults to the current user.

fiftyone.management.api_key.generate_api_key(key_name: str, user: str | User | None = None) → str#

Generates an API key for the given user (default: current user).

Note

Only admins can generate keys for other users.

Warning

Once generated, this key cannot be recovered! If it’s lost, you must generate a new key.

Examples:

import fiftyone.management as fom

# 1. Generate key for myself
fom.generate_api_key("my-key")

# 2.a Generate key for user@example.com
fom.generate_api_key("your-key", "user@example.com")

# 2.b Generate key for user@example.com
user = fom.get_user("user@example.com")
fom.generate_api_key("your-key", user)

Parameters:

key_name – a descriptive name for the key
user (None) – an optional user ID, email string, or User instance. Defaults to the current user.

Returns:

the API key string

fiftyone.management.api_key.list_api_keys(user: str | User | None = None)#

Lists all API keys for the given user (default: current user).

The returned key objects only have their name and IDs populated; the raw key is only available at time of generation.

Note

Only admins can request keys for other users.

Examples:

import fiftyone.management as fom

# 1. List my keys
fom.list_api_keys() # list my keys

# 2.a List keys for user@example.com
fom.list_api_keys("user@example.com")

# 2.b List keys for user@example.com
user = fom.get_user("user@example.com")
fom.list_api_keys(user)

Parameters:: user (None) – an optional user ID, email string, or User instance. Defaults to the current user.
Returns:: a list of APIKey instances

Cloud credentials#

Cloud credentials management.

Copyright 2017-2025, Voxel51, Inc.
voxel51.com

Classes:

`CloudCredential`(created_at, prefixes, provider)	Cloud Credentials Info
`AwsCredentialsFactory`()	Credential factory methods for Amazon AWS provider
`AzureCredentialsFactory`()	Credential factory methods for Microsoft Azure provider
`MinIoCredentialsFactory`()	Credential factory methods for MINIO provider

Functions:

`add_cloud_credentials`(provider, ...[, ...])	Adds cloud credentials to the system.
`delete_cloud_credentials`(provider[, prefixes])	Deletes the installed cloud credentials.
`list_cloud_credentials`()	Lists all cloud credentials installed in the system.

class fiftyone.management.cloud_credentials.CloudCredential(created_at: datetime, prefixes: List[str], provider: str, description: str | None = None)#

Cloud Credentials Info

Attributes:

`created_at`
`prefixes`
`provider`
`description`

created_at: datetime#

prefixes: List[str]#

provider: str#

description: str | None = None#

fiftyone.management.cloud_credentials.add_cloud_credentials(provider: Literal['GCP', 'AWS', 'AZURE', 'MINIO'], credential_type: Literal['ini', 'json', 'factory'], credentials: str | Dict, description: str | None = None, prefixes: List[str] | None = None, overwrite: bool | None = True) → None#

Adds cloud credentials to the system.

Credentials are stored in an encrypted format in the database.

Note

Only admins can add cloud credentials.

Warning

This will overwrite any previously existing credentials with the same provider/prefixes combination.

Warning

Cloud credentials are made available for use for all app users (no access to the credentials themselves). This is for media only and doesn’t affect FiftyOne dataset permissions.

Warning

Raw credentials are sent to the server in plaintext. Ensure that your connection to the server is secure (e.g., via HTTPS) to avoid credentials being intercepted in transit.

Examples:

import os
import fiftyone.management as fom

# Add default GCP credentials from service account json file
fom.add_cloud_credentials(
    "GCP",
    "json",
    "/path/to/gcp-svc-acct.json",
    description="Default GCP credentials"
)

# Add bucket-specific AWS credentials from .ini file
fom.add_cloud_credentials(
    "AWS",
    "ini",
    "/path/to/aws-creds.ini",
    description="Readonly credentials for bucket1,bucket2",
    prefixes=["bucket1", "bucket2"]
)

# Add default AWS credentials from access keys
formatted_credentials = fom.AwsCredentialsFactory.from_access_keys(
    access_key_id=os.environ["AWS_ACCESS_KEY_ID"],
    secret_access_key=os.environ["AWS_SECRET_ACCESS_KEY"],
    default_region="us-west-2"
)

fom.add_cloud_credentials(
    "AWS",
    "factory",
    formatted_credentials,
    description="Default AWS credentials from access keys"
)

Parameters:

provider – the shorthand cloud provider string. One of [“GCP”, “AWS”, “AZURE”, “MINIO”]
credential_type –
Type of credentials passed into credentials param. One of ["ini", "json", "factory"]. ini: Path to an .ini file containing the credentials, such as

/Users/voxel51/.aws/credentials

json: Path to a JSON file containing credentials, such as
/Users/voxel51/.config/gcloud/service-account-creds.json

factory: A dict returned by a class method in one of the
provider-specific credentials factories: AwsCredentialsFactory, AzureCredentialsFactory, MinIoCredentialsFactory
credentials – Dict of factory-built credentials or string path to credentials file, based on credential_type parameter.
description (None) – Optional description for this credential set.
prefixes (None) – The list of bucket names the credentials apply to, if applicable. Defaults to None meaning the default credentials for the provider.
overwrite (True) – Whether to overwrite existing credentials for the same provider/prefixes combination.

Raises:

ValueError – if invalid provider is supplied

fiftyone.management.cloud_credentials.delete_cloud_credentials(provider: Literal['GCP', 'AWS', 'AZURE', 'MINIO'], prefixes: List[str] | None = None) → None#

Deletes the installed cloud credentials.

Note

Only admins can delete cloud credentials.

Warning

This will delete credentials for all app users in the system. Ensure there is another cloud media storage access method in place to avoid system outage.

Examples:

import fiftyone.management as fom

# Delete all credentials for a provider
provider = "AWS"
for credentials in fom.list_cloud_credentials():
    if credentials.provider == provider:
        fom.delete_cloud_credentials(provider, credentials.prefixes)

Parameters:

provider – the shorthand cloud provider string. One of [“GCP”, “AWS”, “AZURE”, “MINIO”]
prefixes (None) – The list of bucket names the credentials apply to, if applicable. Defaults to None meaning the default credentials for the provider.

Raises:

ValueError – if invalid provider is supplied

fiftyone.management.cloud_credentials.list_cloud_credentials() → List[CloudCredential]#

Lists all cloud credentials installed in the system.

The returned credentials objects only have their provider, prefixes, description, and creation time set. You cannot view the plaintext or encrypted credentials.

Note

Only admins can list cloud credentials

Examples:

import fiftyone.management as fom

fom.list_cloud_credentials()

Returns:: a list of CloudCredential instances

class fiftyone.management.cloud_credentials.AwsCredentialsFactory#

Credential factory methods for Amazon AWS provider

Methods:

from_access_keys(access_key_id, ...[, ...])

Get formatted AWS credentials from access keys.

classmethod from_access_keys(access_key_id: str, secret_access_key: str, default_region: str | None = None, session_token: str | None = None) → Dict[str, str]#

Get formatted AWS credentials from access keys.

For use in fom.add_cloud_credentials() only.

Parameters:

access_key_id – AWS access key ID
secret_access_key – AWS secret access key
default_region (None) – default AWS region to set
session_token (None) – AWS session token

Returns:

Formatted credentials

class fiftyone.management.cloud_credentials.AzureCredentialsFactory#

Credential factory methods for Microsoft Azure provider

Methods:

`from_account_key`(account_name, account_key)	Get formatted AZURE credentials from access keys
`from_connection_string`(connection_string[, ...])	Get formatted AZURE credentials from connection string
`from_client_secret`(account_name, client_id, ...)	Get formatted AZURE credentials from client secret

classmethod from_account_key(account_name, account_key, alias: str | None = None) → Dict[str, str]#

Get formatted AZURE credentials from access keys

For use in fom.add_cloud_credentials() only.

Parameters:

account_name – Azure account name
account_key – Azure account key
alias (None) – alias to use for storage blobs

Returns:

Formatted credentials

classmethod from_connection_string(connection_string, alias: str | None = None) → Dict[str, str]#

Get formatted AZURE credentials from connection string

For use in fom.add_cloud_credentials() only.

Parameters:

connection_string – Azure connection string
alias (None) – alias to use for storage blobs

Returns:

Formatted credentials

classmethod from_client_secret(account_name, client_id, client_secret, tenant_id, alias: str | None = None) → Dict[str, str]#

Get formatted AZURE credentials from client secret

For use in fom.add_cloud_credentials() only.

Parameters:

account_name – Azure account name
client_id – Azure client ID
client_secret – Azure client secret
tenant_id – Azure tenant ID
alias (None) – alias to use for storage blobs

Returns:

Formatted credentials

class fiftyone.management.cloud_credentials.MinIoCredentialsFactory#

Credential factory methods for MINIO provider

Methods:

from_access_keys(access_key_id, ...[, ...])

Get formatted MINIO credentials from access keys

classmethod from_access_keys(access_key_id: str, secret_access_key: str, endpoint_url: str, alias: str | None = None, default_region: str | None = None) → Dict[str, str]#

Get formatted MINIO credentials from access keys

For use in fom.add_cloud_credentials() only.

Parameters:

access_key_id – MinIO access key ID
secret_access_key – MinIO secret access key
endpoint_url – MinIO endpoint URL
alias (None) – alias to use for storage blobs
default_region (None) – default MinIO region to set

Returns:

Formatted credentials

Dataset permissions#

Dataset management.

Copyright 2017-2025, Voxel51, Inc.
voxel51.com

Classes:

DatasetPermission(value[, names, module, ...])

Dataset permission enum.

Functions:

`delete_dataset_user_permission`(dataset_name, ...)	Removes the given user's specific access to the given dataset.
`get_dataset_creator`(dataset_name)	Gets creator of a dataset, if known.
`get_permissions`(*[, dataset_name, user, ...])	Gets the specified dataset or user permissions.
`get_permissions_for_dataset`(dataset_name[, ...])	Gets the list of users that have access to the given dataset.
`get_permissions_for_dataset_user`(...)	Gets the access permission (if any) that a given user has to a given dataset.
`get_permissions_for_dataset_user_group`(...)	Gets the access permission (if any) that a given user group has to a given dataset.
`get_permissions_for_user`(user)	Gets a list of datasets a given user has access to.
`get_permissions_for_user_group`(user_group)	Gets a list of datasets a given user group has access to.
`set_dataset_default_permission`(dataset_name, ...)	Sets the default member access level for the given dataset.
`set_dataset_user_permission`(dataset_name, ...)	Grants the given user specific access to the given dataset at the specified permission level.
`set_dataset_user_group_permission`(...)	Grants the given user group specific access to the given dataset at the specified permission level.
`remove_dataset_user_group_permission`(...)	Remove the user group's explicit access to the given dataset

class fiftyone.management.dataset.DatasetPermission(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Dataset permission enum.

Attributes:

`NO_ACCESS`
`VIEW`
`TAG`
`EDIT`
`MANAGE`

NO_ACCESS = 'NO_ACCESS'#

VIEW = 'VIEW'#

TAG = 'TAG'#

EDIT = 'EDIT'#

MANAGE = 'MANAGE'#

fiftyone.management.dataset.delete_dataset_user_permission(dataset_name: str, user: str | User) → None#

Removes the given user’s specific access to the given dataset.

Note

The caller must have Can Manage permissions on the dataset.

Examples:

import fiftyone.management as fom

dataset_name = "special-dataset"
user = "guest@company.com"

fom.set_dataset_user_permission(dataset_name, user, fom.VIEW)

fom.delete_dataset_user_permission(dataset_name, user)

assert fom.get_permissions(dataset_name=dataset_name, user=user) == fom.NO_ACCESS

Parameters:

dataset_name – the dataset name
user – a user ID, email string, or User instance.

fiftyone.management.dataset.get_dataset_creator(dataset_name: str) → User | None#

Gets creator of a dataset, if known.

Examples:

import fiftyone.management as fom

user = fom.get_dataset_creator("dataset")

Parameters:: dataset_name – the dataset name
Raises:: ValueError – if dataset_name does not exist or calling user does not have access to it.
Returns:: User instance, or None if dataset has no recorded creator.

fiftyone.management.dataset.get_permissions(*, dataset_name: str = None, user: str | User = None, user_group: str | UserGroup = None)#

Gets the specified dataset or user permissions.

This method is a convenience wrapper around the methods below based on which arguments you provide:

dataset_name: get_permissions_for_dataset()
user: get_permissions_for_user()
user_group: get_permissions_for_dataset_user_group()
dataset_name and user: get_permissions_for_dataset_user()
dataset_name and user_group:
get_permissions_for_dataset_user_group()

Note

Only admins can retrieve this information.

Examples:

import fiftyone.management as fom

dataset_name = "special-dataset"
user = "guest@company.com"

# Get permissions for user
assert (
    fom.get_permissions(user=user) ==
    fom.get_permissions_for_user(user)
)

# Get permissions for dataset
assert (
    fom.get_permissions(dataset_name=dataset_name) ==
    fom.get_permissions_for_dataset(dataset_name)
)

# Get permissions for user-dataset combination
assert (
    fom.get_permissions(dataset_name=dataset_name, user=user) ==
    fom.get_permissions_for_dataset_user(dataset_name, user)
)

# Get permissions for user group-dataset
assert (
    fom.get_permissions(dataset_name=dataset_name,
        user_group="some-id") ==
    fom.get_permissions_for_dataset_user_group(dataset_name, "some-id")
)

Parameters:

dataset_name (None) – a dataset name
user (None) – a user ID, email string, or User instance
user_group (None) – a user group ID or name string, or a UserGroup instance

Returns:

the requested user/dataset permissions

fiftyone.management.dataset.get_permissions_for_dataset(dataset_name: str, include_groups=True) → Dict#

Gets the list of users that have access to the given dataset.

Note

Only admins can retrieve this information.

Examples:

import fiftyone.management as fom

dataset_name = "special-dataset"

fom.get_permissions_for_dataset(dataset_name)

Example output:

[
    {'name': 'A. User', 'email': 'a@company.com', 'id': '12345', 'permission': 'MANAGE'},
    {'name': 'B. User', 'email': 'b@company.com', 'id': '67890', 'permission': 'EDIT'},
]

Parameters:

dataset_name – the dataset name

Returns:

If include_groups is True, return a dictionary contains a list of user: info and group info. Otherwise, return a list of user info.

fiftyone.management.dataset.get_permissions_for_dataset_user(dataset_name: str, user: str) → DatasetPermission#

Gets the access permission (if any) that a given user has to a given dataset.

Note

Only admins can retrieve this information.

Examples:

import fiftyone.management as fom

dataset_name = "special-dataset"
user = "guest@company.com"

fom.get_permissions_for_dataset_user(dataset_name, user)

Parameters:

dataset_name – the dataset name
user – a user ID, email string, or User instance

Returns:

DatasetPermission

fiftyone.management.dataset.get_permissions_for_dataset_user_group(dataset_name: str, user_group: str | UserGroup) → DatasetPermission#

Gets the access permission (if any) that a given user group has to a given dataset.

Note

Only admins can retrieve this information.

Examples:

import fiftyone.management as fom

dataset_name = "special-dataset"
user_group = "interns"

fom.get_permissions_for_dataset_user_group(dataset_name, user_group)

Parameters:

dataset_name – the dataset name
user_group – a user group ID or name string or UserGroup

Returns:

DatasetPermission

fiftyone.management.dataset.get_permissions_for_user(user: str)#

Gets a list of datasets a given user has access to.

Note

Only admins can retrieve this information.

Examples:

import fiftyone.management as fom

user = "guest@company.com"

fom.get_permissions_for_user(user)

Example output:

[
    {'name': 'datasetA', 'permission': 'EDIT'},
    {'name': 'datasetB', 'permission': 'VIEW'},
]

Parameters:: user – a user ID, email string, or User instance
Returns:: a list of permission dicts

fiftyone.management.dataset.get_permissions_for_user_group(user_group: str | UserGroup)#

Gets a list of datasets a given user group has access to.

Note

Only admins can retrieve this information.

Examples:

import fiftyone.management as fom

user_group = "some-group-id"

fom.get_permissions_for_user_group(user_group)

Example output:

[
    {'name': 'datasetA', 'permission': 'EDIT'},
    {'name': 'datasetB', 'permission': 'VIEW'},
]

Parameters:: user_group – a user group ID or name or UserGroup
Returns:: a list of permission dicts

fiftyone.management.dataset.set_dataset_default_permission(dataset_name: str, permission: DatasetPermission) → None#

Sets the default member access level for the given dataset.

Note

The caller must have Can Manage permissions on the dataset.

Examples:

import fiftyone.management as fom

dataset_name = "special-dataset"

# Give every Member Edit access by default
fom.set_dataset_default_permission(dataset_name, fom.EDIT)

Parameters:

dataset_name – the dataset name
permission – the DatasetPermission to set

fiftyone.management.dataset.set_dataset_user_permission(dataset_name: str, user: str | User, permission: DatasetPermission, invite: bool = False) → None#

Grants the given user specific access to the given dataset at the specified permission level.

Note

The caller must have Can Manage permissions on the dataset.

Warning

If an unknown email is passed to this function and invite is True, an invitation to join the organization will be sent to the email. The user will be created and have access to the dataset on invitation acceptance. Please double-check the email correctness before running.

Examples:

import fiftyone.management as fom

dataset_name = "special-dataset"
guest = "guest@company.com"
new_guest = "new-guest@company.com"

# Existing user
fom.set_dataset_user_permission(dataset_name, guest, fom.VIEW)

assert fom.get_permissions(dataset_name=dataset_name, user=guest) == fom.VIEW

# Nonexisting user
fom.set_dataset_user_permission(dataset_name, new_guest, fom.VIEW, invite=True)
assert guest in [i.invitee_email for i in fom.list_pending_invitations()]

Parameters:

dataset_name – the dataset name
user – a user ID, email string, or User instance
permission – the DatasetPermission to grant
invite (False) – if True and user is an email, an invitation will be sent to join the organization.

fiftyone.management.dataset.set_dataset_user_group_permission(dataset_name: str, user_group: str | UserGroup, permission: str | DatasetPermission) → None#

Grants the given user group specific access to the given dataset at the specified permission level.

Note

The caller must have Can Manage permissions on the dataset.

Examples:

import fiftyone.management as fom

dataset_name = "special-dataset"
group_id = "some-group-id"

fom.set_dataset_user_permission(dataset_name, group_id, fom.VIEW)

Parameters:

dataset_name – the dataset name
user_group – a user group ID or name string or a UserGroup instance
permission – the DatasetPermission

fiftyone.management.dataset.remove_dataset_user_group_permission(dataset_name: str, user_group: str | UserGroup) → None#

Remove the user group’s explicit access to the given dataset

Note

The caller must have Can Manage permissions on the dataset.

Examples:

import fiftyone.management as fom

dataset_name = "special-dataset"
group_id = "some-group-id"

fom.remove_dataset_user_group_permission(dataset_name, group_id)

Parameters:

dataset_name – the dataset name
user_group – a user group id or name string or a UserGroup instance

Organization settings#

Organization settings management.

Copyright 2017-2025, Voxel51, Inc.
voxel51.com

Classes:

OrganizationSettings(default_user_role, ...)

Functions:

`get_organization_settings`()	Gets organization-wide settings for the FiftyOne Enterprise deployment.
`set_organization_settings`(*[, ...])	Sets organization-wide settings for the FiftyOne Enterprise deployment.

class fiftyone.management.organization.OrganizationSettings(default_user_role: fiftyone.management.users.UserRole, default_dataset_permission: fiftyone.management.dataset.DatasetPermission, default_operator_minimum_role: fiftyone.management.users.UserRole, default_operator_minimum_dataset_permission: fiftyone.management.dataset.DatasetPermission)#

Attributes:

`default_user_role`
`default_dataset_permission`
`default_operator_minimum_role`
`default_operator_minimum_dataset_permission`

default_user_role: UserRole#

default_dataset_permission: DatasetPermission#

default_operator_minimum_role: UserRole#

default_operator_minimum_dataset_permission: DatasetPermission#

fiftyone.management.organization.get_organization_settings() → OrganizationSettings#

Gets organization-wide settings for the FiftyOne Enterprise deployment.

Note

Only admins can retrieve this information

Examples:

import fiftyone.management as fom

fom.get_organization_settings()

Returns:: OrganizationSettings

fiftyone.management.organization.set_organization_settings(*, default_user_role: UserRole | None = None, default_dataset_permission: DatasetPermission | None = None, default_operator_minimum_role: UserRole | None = None, default_operator_minimum_dataset_permission: DatasetPermission | None = None) → OrganizationSettings#

Sets organization-wide settings for the FiftyOne Enterprise deployment.

Note

Only admins can perform this action.

Examples:

import fiftyone.management as fom

user_role = fom.MEMBER
dataset_perm = fom.EDIT

# Set only default user role
fom.set_organization_settings(default_user_role=user_role)

# Set only default dataset permission
fom.set_organization_settings(default_dataset_permission=dataset_perm)

# Set multiple settings at once
fom.set_organization_settings(
    default_user_role=user_role,
    default_dataset_permission=dataset_perm,
    default_operator_minimum_role=user_role,
    default_operator_minimum_dataset_permission=dataset_perm,
)

Parameters:

default_user_role (None) – an optional UserRole to set.
default_dataset_permission (None) – an optional DatasetPermission to set,
default_operator_minimum_role (None) – an optional UserRole to set
default_operator_minimum_dataset_permission (None) – an optional DatasetPermission to set

Returns:

OrganizationSettings

Plugin management#

Plugin management.

Copyright 2017-2025, Voxel51, Inc.
voxel51.com

Classes:

`OperatorPermission`(minimum_role, ...)	Operator permission dataclass.
`PluginOperator`(name, enabled, permission)	Plugin operator dataclass.
`Plugin`(name, description, version, ...)	Plugin dataclass.

Functions:

`list_plugins`([include_builtin])	Returns a list of all installed plugins in the FiftyOne Enterprise deployment.
`get_plugin_info`(plugin_name)	Gets information about the specified plugin in the FiftyOne Enterprise deployment.
`upload_plugin`(plugin_path[, overwrite, optimize])	Uploads a plugin to the FiftyOne Enterprise deployment.
`delete_plugin`(plugin_name)	Deletes the given plugin from the FiftyOne Enterprise deployment.
`download_plugin`(plugin_name, download_dir)	Downloads a plugin from the FiftyOne Enterprise deployment.
`set_plugin_enabled`(plugin_name, enabled)	Sets the enabled status of the given plugin in the FiftyOne Enterprise deployment.
`set_plugin_operator_enabled`(plugin_name, ...)	Sets the enabled status of the given plugin operator in the FiftyOne Enterprise deployment.
`set_plugin_operator_permissions`(plugin_name, ...)	Sets permission levels of the given plugin operator in the FiftyOne Enterprise deployment.

class fiftyone.management.plugin.OperatorPermission(minimum_role: UserRole, minimum_dataset_permission: DatasetPermission)#

Operator permission dataclass.

Attributes:

`minimum_role`
`minimum_dataset_permission`

minimum_role: UserRole#

minimum_dataset_permission: DatasetPermission#

class fiftyone.management.plugin.PluginOperator(name: str, enabled: bool, permission: OperatorPermission)#

Plugin operator dataclass.

Attributes:

`name`
`enabled`
`permission`

name: str#

enabled: bool#

permission: OperatorPermission#

class fiftyone.management.plugin.Plugin(name: str, description: str, version: str, fiftyone_version: str, enabled: bool, operators: List[PluginOperator])#

Plugin dataclass.

Attributes:

`name`
`description`
`version`
`fiftyone_version`
`enabled`
`operators`

name: str#

description: str#

version: str#

fiftyone_version: str#

enabled: bool#

operators: List[PluginOperator]#

fiftyone.management.plugin.list_plugins(include_builtin: bool = False) → List[Plugin]#

Returns a list of all installed plugins in the FiftyOne Enterprise deployment.

Examples:

import fiftyone.management as fom

fom.list_plugins()

Parameters:: include_builtin (False) – whether to include builtin plugins
Returns:: a list of Plugin instances

fiftyone.management.plugin.get_plugin_info(plugin_name: str) → Plugin#

Gets information about the specified plugin in the FiftyOne Enterprise deployment.

Examples:

import fiftyone.management as fom

fom.get_plugin_info("my-plugin")

Parameters:: plugin_name – a plugin name
Returns:: Plugin, or None if no such plugin is found

fiftyone.management.plugin.upload_plugin(plugin_path: str, overwrite: bool = False, optimize=False) → Plugin#

Uploads a plugin to the FiftyOne Enterprise deployment.

The local plugin must be a zip file that contains a single directory with a fiftyone.yml or fiftyone.yaml file. For example:

my_plugin/
    fiftyone.yml
    __init__.py
    data.txt

Note

Only admins can upload plugins.

Examples:

import fiftyone.management as fom

# Upload a raw plugin directory
fom.upload_plugin("/path/to/plugin_dir", overwrite=True)

# Upload a plugin, optimizing the directory before the upload
fom.upload_plugin("/path/to/plugin_dir", overwrite=True, optimize=True)

# Upload a plugin as ZIP file
fom.upload_plugin("/path/to/plugin.zip", overwrite=True)

Parameters:

plugin_path – the path to a plugin zip or directory
overwrite (False) – whether to overwrite an existing plugin with same name
optimize (False) – whether to optimize the created zip file before uploading. If a .gitignore file exists, an attempt will first be made to use git archive to create the zip. If not or this doesn’t work, a zip will be created by pruning various known system-generated files and directories such as .git/ and __pycache__/. This argument has no effect if plugin_path does not point to a directory

fiftyone.management.plugin.delete_plugin(plugin_name: str) → None#

Deletes the given plugin from the FiftyOne Enterprise deployment.

Examples:

import fiftyone.management as fom

plugin_name = "special-plugin"
fom.delete_plugin(plugin_name)

plugins = fom.list_plugins()
assert not any(plugin.name == plugin_name for plugin in plugins)

Note

Only admins can perform this action.

Parameters:: plugin_name – a plugin name

fiftyone.management.plugin.download_plugin(plugin_name: str, download_dir: str) → str#

Downloads a plugin from the FiftyOne Enterprise deployment.

Examples:

import fiftyone.management as fom

fom.download_plugin("special-plugin", "/path/to/local/plugins/")

Parameters:

plugin_name – a plugin name
download_dir – a directory into which to download the plugin

Returns:

the path to the downloaded plugin

fiftyone.management.plugin.set_plugin_enabled(plugin_name: str, enabled: bool) → None#

Sets the enabled status of the given plugin in the FiftyOne Enterprise deployment.

Note

Only admins can perform this action.

Examples:

import fiftyone.management as fom

# Disable whole plugin
fom.set_plugin_enabled("special-plugin", False)

Parameters:

plugin_name – a plugin name
enabled – a bool specifying what to set enabled status to

fiftyone.management.plugin.set_plugin_operator_enabled(plugin_name: str, operator_name: str, enabled: bool) → None#

Sets the enabled status of the given plugin operator in the FiftyOne Enterprise deployment.

Note

Only admins can perform this action.

Examples:

import fiftyone.management as fom

# Disable a particular operator
fom.set_plugin_operator_enabled("special-plugin", "special-operator", False)

Parameters:

plugin_name – a plugin name
operator_name – an operator name within the given plugin
enabled – a bool specifying what to set operator enabled status to

fiftyone.management.plugin.set_plugin_operator_permissions(plugin_name: str, operator_name: str, minimum_role: UserRole | None = None, minimum_dataset_permission: DatasetPermission | None = None)#

Sets permission levels of the given plugin operator in the FiftyOne Enterprise deployment.

At least one of minimum_role and minimum_dataset_permission must be set.

Note

Only admins can perform this action.

Examples:

import fiftyone.management as fom

plugin_name = "special-plugin"
operator_name = "special-operator"

# Set minimum role permission only
fom.set_plugin_operator_permissions(
    plugin_name,
    operator_name,
    minimum_role=fom.MEMBER
    )

# Set minimum dataset permission only
fom.set_plugin_operator_permissions(
    plugin_name,
    operator_name,
    minimum_dataset_permission=fom.EDIT
)

# Set both minimum role and minimum dataset permissions
fom.set_plugin_operator_permissions(
    plugin_name,
    operator_name,
    minimum_role=fom.EDIT,
    minimum_dataset_permission=fom.EDIT
)

Parameters:

plugin_name – a plugin name
operator_name – an operator name within the given plugin
minimum_role (None) – an optional UserRole to set
minimum_dataset_permission (None) – an optional DatasetPermission to set

Orchestrator management#

Orchestrator management.

Copyright 2017-2025, Voxel51, Inc.
voxel51.com

Classes:

`OrchestratorEnvironment`(value[, names, ...])	Orchestrator environment types.
`OrchestratorDocument`(instance_identifier[, ...])	Orchestrator document representation.

Functions:

`get_orchestrator`(instance_id[, user])	Retrieves an orchestrator by its instance identifier.
`list_orchestrators`([include_deactivated])	Lists orchestrators with pagination, filtering, and sorting.
`register_orchestrator`(instance_id, ...)	Registers a new orchestrator to run delegated operations.
`delete_orchestrator`(instance_id)	Deletes an orchestrator by its instance identifier.

class fiftyone.management.orchestrator.OrchestratorEnvironment(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Orchestrator environment types.

Attributes:

`DATABRICKS`
`ANYSCALE`
`SELF_REGISTERED`

Methods:

`map_to_graphql_value`()	Maps the enum value to its GraphQL value
`map_from_graphql_value`(value)	Maps a GraphQL value to the enum value
`encode`([encoding, errors])	Encode the string using the codec registered for encoding.
`replace`(old, new[, count])	Return a copy with all occurrences of substring old replaced by new.
`split`([sep, maxsplit])	Return a list of the substrings in the string, using sep as the separator string.
`rsplit`([sep, maxsplit])	Return a list of the substrings in the string, using sep as the separator string.
`join`(iterable, /)	Concatenate any number of strings.
`capitalize`()	Return a capitalized version of the string.
`casefold`()	Return a version of the string suitable for caseless comparisons.
`title`()	Return a version of the string where each word is titlecased.
`center`(width[, fillchar])	Return a centered string of length width.
`count`(sub[, start[, end]])	Return the number of non-overlapping occurrences of substring sub in string S[start:end].
`expandtabs`([tabsize])	Return a copy where all tab characters are expanded using spaces.
`find`(sub[, start[, end]])	Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end].
`partition`(sep, /)	Partition the string into three parts using the given separator.
`index`(sub[, start[, end]])	Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end].
`ljust`(width[, fillchar])	Return a left-justified string of length width.
`lower`()	Return a copy of the string converted to lowercase.
`lstrip`([chars])	Return a copy of the string with leading whitespace removed.
`rfind`(sub[, start[, end]])	Return the highest index in S where substring sub is found, such that sub is contained within S[start:end].
`rindex`(sub[, start[, end]])	Return the highest index in S where substring sub is found, such that sub is contained within S[start:end].
`rjust`(width[, fillchar])	Return a right-justified string of length width.
`rstrip`([chars])	Return a copy of the string with trailing whitespace removed.
`rpartition`(sep, /)	Partition the string into three parts using the given separator.
`splitlines`([keepends])	Return a list of the lines in the string, breaking at line boundaries.
`strip`([chars])	Return a copy of the string with leading and trailing whitespace removed.
`swapcase`()	Convert uppercase characters to lowercase and lowercase characters to uppercase.
`translate`(table, /)	Replace each character in the string using the given translation table.
`upper`()	Return a copy of the string converted to uppercase.
`startswith`(prefix[, start[, end]])	Return True if S starts with the specified prefix, False otherwise.
`endswith`(suffix[, start[, end]])	Return True if S ends with the specified suffix, False otherwise.
`removeprefix`(prefix, /)	Return a str with the given prefix string removed if present.
`removesuffix`(suffix, /)	Return a str with the given suffix string removed if present.
`isascii`()	Return True if all characters in the string are ASCII, False otherwise.
`islower`()	Return True if the string is a lowercase string, False otherwise.
`isupper`()	Return True if the string is an uppercase string, False otherwise.
`istitle`()	Return True if the string is a title-cased string, False otherwise.
`isspace`()	Return True if the string is a whitespace string, False otherwise.
`isdecimal`()	Return True if the string is a decimal string, False otherwise.
`isdigit`()	Return True if the string is a digit string, False otherwise.
`isnumeric`()	Return True if the string is a numeric string, False otherwise.
`isalpha`()	Return True if the string is an alphabetic string, False otherwise.
`isalnum`()	Return True if the string is an alpha-numeric string, False otherwise.
`isidentifier`()	Return True if the string is a valid Python identifier, False otherwise.
`isprintable`()	Return True if the string is printable, False otherwise.
`zfill`(width, /)	Pad a numeric string with zeros on the left, to fill a field of the given width.
`format`(args, *kwargs)	Return a formatted version of S, using substitutions from args and kwargs.
`format_map`(mapping)	Return a formatted version of S, using substitutions from mapping.
`maketrans`	Return a translation table usable for str.translate().

DATABRICKS = 'databricks'#

ANYSCALE = 'anyscale'#

SELF_REGISTERED = 'self_registered'#

map_to_graphql_value() → str#: Maps the enum value to its GraphQL value

classmethod map_from_graphql_value(value: str) → OrchestratorEnvironment#: Maps a GraphQL value to the enum value

encode(encoding='utf-8', errors='strict')#

Encode the string using the codec registered for encoding.

encoding: The encoding in which to encode the string.
errors: The error handling scheme to use for encoding errors. The default is ‘strict’ meaning that encoding errors raise a UnicodeEncodeError. Other possible values are ‘ignore’, ‘replace’ and ‘xmlcharrefreplace’ as well as any other name registered with codecs.register_error that can handle UnicodeEncodeErrors.

replace(old, new, count=-1, /)#

Return a copy with all occurrences of substring old replaced by new.

count
Maximum number of occurrences to replace. -1 (the default value) means replace all occurrences.

If the optional argument count is given, only the first count occurrences are replaced.

split(sep=None, maxsplit=-1)#

Return a list of the substrings in the string, using sep as the separator string.

sep
The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

maxsplit
Maximum number of splits. -1 (the default value) means no limit.

Splitting starts at the front of the string and works to the end.

Note, str.split() is mainly useful for data that has been intentionally delimited. With natural text that includes punctuation, consider using the regular expression module.

rsplit(sep=None, maxsplit=-1)#

Return a list of the substrings in the string, using sep as the separator string.

sep
The separator used to split the string.

When set to None (the default value), will split on any whitespace character (including n r t f and spaces) and will discard empty strings from the result.

maxsplit
Maximum number of splits. -1 (the default value) means no limit.

Splitting starts at the end of the string and works to the front.

join(iterable, /)#

Concatenate any number of strings.

The string whose method is called is inserted in between each given string. The result is returned as a new string.

Example: ‘.’.join([‘ab’, ‘pq’, ‘rs’]) -> ‘ab.pq.rs’

capitalize()#

Return a capitalized version of the string.

More specifically, make the first character have upper case and the rest lower case.

casefold()#: Return a version of the string suitable for caseless comparisons.

title()#

Return a version of the string where each word is titlecased.

More specifically, words start with uppercased characters and all remaining cased characters have lower case.

center(width, fillchar=' ', /)#

Return a centered string of length width.

Padding is done using the specified fill character (default is a space).

count(sub[, start[, end]]) → int#: Return the number of non-overlapping occurrences of substring sub in string S[start:end]. Optional arguments start and end are interpreted as in slice notation.

expandtabs(tabsize=8)#

Return a copy where all tab characters are expanded using spaces.

If tabsize is not given, a tab size of 8 characters is assumed.

find(sub[, start[, end]]) → int#

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Return -1 on failure.

partition(sep, /)#

Partition the string into three parts using the given separator.

This will search for the separator in the string. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing the original string and two empty strings.

index(sub[, start[, end]]) → int#

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Raises ValueError when the substring is not found.

ljust(width, fillchar=' ', /)#

Return a left-justified string of length width.

Padding is done using the specified fill character (default is a space).

lower()#: Return a copy of the string converted to lowercase.

lstrip(chars=None, /)#

Return a copy of the string with leading whitespace removed.

If chars is given and not None, remove characters in chars instead.

rfind(sub[, start[, end]]) → int#

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Return -1 on failure.

rindex(sub[, start[, end]]) → int#

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Raises ValueError when the substring is not found.

rjust(width, fillchar=' ', /)#

Return a right-justified string of length width.

Padding is done using the specified fill character (default is a space).

rstrip(chars=None, /)#

Return a copy of the string with trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

rpartition(sep, /)#

Partition the string into three parts using the given separator.

This will search for the separator in the string, starting at the end. If the separator is found, returns a 3-tuple containing the part before the separator, the separator itself, and the part after it.

If the separator is not found, returns a 3-tuple containing two empty strings and the original string.

splitlines(keepends=False)#

Return a list of the lines in the string, breaking at line boundaries.

Line breaks are not included in the resulting list unless keepends is given and true.

strip(chars=None, /)#

Return a copy of the string with leading and trailing whitespace removed.

If chars is given and not None, remove characters in chars instead.

swapcase()#: Convert uppercase characters to lowercase and lowercase characters to uppercase.

translate(table, /)#

Replace each character in the string using the given translation table.

table
Translation table, which must be a mapping of Unicode ordinals to Unicode ordinals, strings, or None.

The table must implement lookup/indexing via __getitem__, for instance a dictionary or list. If this operation raises LookupError, the character is left untouched. Characters mapped to None are deleted.

upper()#: Return a copy of the string converted to uppercase.

startswith(prefix[, start[, end]]) → bool#: Return True if S starts with the specified prefix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. prefix can also be a tuple of strings to try.

endswith(suffix[, start[, end]]) → bool#: Return True if S ends with the specified suffix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. suffix can also be a tuple of strings to try.

removeprefix(prefix, /)#

Return a str with the given prefix string removed if present.

If the string starts with the prefix string, return string[len(prefix):]. Otherwise, return a copy of the original string.

removesuffix(suffix, /)#

Return a str with the given suffix string removed if present.

If the string ends with the suffix string and that suffix is not empty, return string[:-len(suffix)]. Otherwise, return a copy of the original string.

isascii()#

Return True if all characters in the string are ASCII, False otherwise.

ASCII characters have code points in the range U+0000-U+007F. Empty string is ASCII too.

islower()#

Return True if the string is a lowercase string, False otherwise.

A string is lowercase if all cased characters in the string are lowercase and there is at least one cased character in the string.

isupper()#

Return True if the string is an uppercase string, False otherwise.

A string is uppercase if all cased characters in the string are uppercase and there is at least one cased character in the string.

istitle()#

Return True if the string is a title-cased string, False otherwise.

In a title-cased string, upper- and title-case characters may only follow uncased characters and lowercase characters only cased ones.

isspace()#

Return True if the string is a whitespace string, False otherwise.

A string is whitespace if all characters in the string are whitespace and there is at least one character in the string.

isdecimal()#

Return True if the string is a decimal string, False otherwise.

A string is a decimal string if all characters in the string are decimal and there is at least one character in the string.

isdigit()#

Return True if the string is a digit string, False otherwise.

A string is a digit string if all characters in the string are digits and there is at least one character in the string.

isnumeric()#

Return True if the string is a numeric string, False otherwise.

A string is numeric if all characters in the string are numeric and there is at least one character in the string.

isalpha()#

Return True if the string is an alphabetic string, False otherwise.

A string is alphabetic if all characters in the string are alphabetic and there is at least one character in the string.

isalnum()#

Return True if the string is an alpha-numeric string, False otherwise.

A string is alpha-numeric if all characters in the string are alpha-numeric and there is at least one character in the string.

isidentifier()#

Return True if the string is a valid Python identifier, False otherwise.

Call keyword.iskeyword(s) to test whether string s is a reserved identifier, such as “def” or “class”.

isprintable()#

Return True if the string is printable, False otherwise.

A string is printable if all of its characters are considered printable in repr() or if it is empty.

zfill(width, /)#

Pad a numeric string with zeros on the left, to fill a field of the given width.

The string is never truncated.

format(*args, **kwargs) → str#: Return a formatted version of S, using substitutions from args and kwargs. The substitutions are identified by braces (‘{’ and ‘}’).

format_map(mapping) → str#: Return a formatted version of S, using substitutions from mapping. The substitutions are identified by braces (‘{’ and ‘}’).

static maketrans()#

Return a translation table usable for str.translate().

If there is only one argument, it must be a dictionary mapping Unicode ordinals (integers) or characters to Unicode ordinals, strings or None. Character keys will be then converted to ordinals. If there are two arguments, they must be strings of equal length, and in the resulting dictionary, each character in x will be mapped to the character at the same position in y. If there is a third argument, it must be a string, whose characters will be mapped to None in the result.

class fiftyone.management.orchestrator.OrchestratorDocument(instance_identifier: str, description: str = None, environment: str = OrchestratorEnvironment.SELF_REGISTERED, available_operators: List[str] = None, config: Dict | None = None, secrets: Dict | None = None, created_at: datetime | None = None, updated_at: datetime | None = None)#

Orchestrator document representation.

Attributes:

`instance_identifier`
`description`
`environment`
`available_operators`
`config`
`secrets`
`created_at`
`updated_at`

instance_identifier: str#

description: str = None#

environment: str = 'self_registered'#

available_operators: List[str] = None#

config: Dict | None = None#

secrets: Dict | None = None#

created_at: datetime | None = None#

updated_at: datetime | None = None#

fiftyone.management.orchestrator.get_orchestrator(instance_id: str, user: str | User = None) → OrchestratorDocument#

Retrieves an orchestrator by its instance identifier.

Parameters:

instance_id – the instance identifier / unique name of the orchestrator
user – the user requesting the orchestrator (optional)

Returns:

the orchestrator document

Raises:

ValueError – if the orchestrator doesn’t exist

fiftyone.management.orchestrator.list_orchestrators(include_deactivated: bool = False) → List[str]#

Lists orchestrators with pagination, filtering, and sorting.

Parameters:

page – the page number (1-indexed)
filters – filter criteria (e.g., {“include_deactivated”: True})

Returns:

a list of orchestrator instance_identifiers

fiftyone.management.orchestrator.register_orchestrator(instance_id: str, description: str, environment: str | OrchestratorEnvironment, config: Dict | None, secrets: Dict | None) → OrchestratorDocument#

Registers a new orchestrator to run delegated operations.

Any secrets provided will be stored in the FiftyOne secrets store, encrypted.

Parameters:

instance_id – the instance identifier of the orchestrator
description – the description of the orchestrator
environment – the orchestrator environment (e.g., “databricks”, “anyscale”)
config – environment-specific configuration
secrets – environment-specific secrets

Note

The config and secrets fields must include a top-level key that corresponds to the environment

Warning

Raw secret values are sent to the server in plaintext. Ensure that your connection to the server is secure (e.g., via HTTPS) to avoid secrets being intercepted in transit.

Examples:

# databricks config example
{
    "databricks": {
        "jobId": "1234567890abcdef",
        "executionTaskId": "0987654321fedcba",
        "registrationTaskId": "a12b3c4d"
    }
}

# anyscale config example
{
    "anyscale": {
        "jobQueueName": "JobQueueName",
        "imageUri": "an-image-uri",
        "executionComputeConfig": "exec-config"
    }
}

# databricks secrets example
{
    "databricks": {
        "host": "host_name",
        "accountId": "account_id",
        "clientId": "your_client_id",
        "clientSecret": "your_client_secret",
    }
}

# anyscale secrets example
{
    "anyscale": {
        "authToken": "your_auth_token",
    }
}

Returns:: the registered orchestrator document
Raises:: ValueError – if environment is invalid or config is missing required fields

fiftyone.management.orchestrator.delete_orchestrator(instance_id: str) → None#

Deletes an orchestrator by its instance identifier.

Parameters:: instance_id – the instance identifier of the orchestrator to delete
Raises:: ValueError – if the orchestrator doesn’t exist

Secrets#

Secrets management.

Copyright 2017-2025, Voxel51, Inc.
voxel51.com

Classes:

FiftyOneSecret(created_at, key[, description])

Secret Info

Functions:

`add_secret`(key, value[, description])	Adds a secret for use by FiftyOne plugins.
`delete_secret`(key)	Deletes the uploaded secret.
`get_secret_info`(key)	Get information about a FiftyOne secret.
`list_secrets`()	Lists the keys for all secrets installed in the system.
`update_secret`(key[, value, description])	Updates an existing secret for use by FiftyOne plugins.

class fiftyone.management.secret.FiftyOneSecret(created_at: datetime, key: str, description: str | None = None)#

Secret Info

Attributes:

`created_at`
`key`
`description`

created_at: datetime#

key: str#

description: str | None = None#

fiftyone.management.secret.add_secret(key: str, value: str, description: str | None = None) → None#

Adds a secret for use by FiftyOne plugins.

Secrets are stored in an encrypted format in the database.

Note

Only admins can add secrets.

Warning

Raw secret values are sent to the server in plaintext. Ensure that your connection to the server is secure (e.g., via HTTPS) to avoid secrets being intercepted in transit.

Examples:

import fiftyone.management as fom

fom.add_secret(
    "MY_SECRET",
    "PASSWORD12345",
    description="very secure secret"
)

Parameters:

key – String key of the secret.
value – Value to give the secret. It’s encrypted upon upload.
description (None) – Optional description for this secret.

fiftyone.management.secret.delete_secret(key: str) → None#

Deletes the uploaded secret.

Note

Only admins can delete secrets.

Warning

This will delete the secret for all users. A new value will need to be uploaded if a plugin requires this secret.

Examples:

import fiftyone.management as fom

fom.delete_secret("MY_SECRET")

Parameters:: key – string key of secret to delete

fiftyone.management.secret.get_secret_info(key: str) → FiftyOneSecret | None#

Get information about a FiftyOne secret.

The returned secret object only has certain fields set. You cannot view the plaintext or encrypted value of the secret.

Examples:

import fiftyone.management as fom

fom.get_secret_info("MY_SECRET")

Parameters:: key – string key of secret to get info on
Returns:: A FiftyOneSecret instance, or None if the secret doesn’t exist.

fiftyone.management.secret.list_secrets() → List[str]#

Lists the keys for all secrets installed in the system.

The returned secret object only have their provider, prefixes, description, and creation time set. You cannot view the plaintext or encrypted value.

Note

Only admins can list secrets

Examples:

import fiftyone.management as fom

fom.list_secrets()

Returns:: a list of FiftyOneSecret instances

fiftyone.management.secret.update_secret(key: str, value: str | None = None, description: str | None = None) → None#

Updates an existing secret for use by FiftyOne plugins.

Secrets are stored in an encrypted format in the database.

Note

Only admins can update secrets.

Warning

Raw secret values are sent to the server in plaintext. Ensure that your connection to the server is secure (e.g., via HTTPS) to avoid secrets being intercepted in transit.

Examples:

import fiftyone.management as fom

fom.update_secret(
    "MY_SECRET",
    "PASSWORD12345",
    description="very secure secret"
)

Parameters:

key – String key of the existing secret.
value (None) – Optional Value to update on the secret.
description (None) – Optional description to update on the secret.

Snapshots#

Dataset snapshot management.

Copyright 2017-2025, Voxel51, Inc.
voxel51.com

Classes:

`DatasetSnapshotStatus`(value[, names, ...])	User role enum.
`SampleChangeSummary`(total_samples, ...[, ...])
`DatasetSnapshot`(created_at, created_by, ...)

Functions:

`archive_snapshot`(dataset_name, snapshot_name)	Archive snapshot to the configured cold storage location.
`calculate_dataset_latest_changes_summary`(...)	Calculate change summary between recent snapshot and HEAD of dataset.
`create_snapshot`(dataset_name, snapshot_name)	Create and store a snapshot of the current state of `dataset_name`.
`delete_snapshot`(dataset_name, snapshot_name)	Delete snapshot `snapshot_name` from dataset `dataset_name`.
`get_dataset_latest_changes_summary`(dataset_name)	Gets change summary between most recent snapshot and HEAD of dataset
`get_snapshot_info`(dataset_name, snapshot_name)	Gets information about the specified dataset snapshot, or `None`
`list_snapshots`(dataset_name)	Returns a list of all snapshots of a dataset in order of creation.
`revert_dataset_to_snapshot`(dataset_name, ...)	Revert dataset to a previous snapshot state.
`unarchive_snapshot`(dataset_name, snapshot_name)	Unarchive snapshot from the configured cold storage location.

class fiftyone.management.snapshot.DatasetSnapshotStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

User role enum.

Attributes:

`UNLOADED`
`LOADING`
`LOADED`

UNLOADED = 'UNLOADED'#

LOADING = 'LOADING'#

LOADED = 'LOADED'#

class fiftyone.management.snapshot.SampleChangeSummary(total_samples: int, num_samples_added: int, num_samples_deleted: int, num_samples_changed: int, updated_at: datetime.datetime | None = None)#

Attributes:

`total_samples`
`num_samples_added`
`num_samples_deleted`
`num_samples_changed`
`updated_at`

total_samples: int#

num_samples_added: int#

num_samples_deleted: int#

num_samples_changed: int#

updated_at: datetime | None = None#

class fiftyone.management.snapshot.DatasetSnapshot(created_at: datetime.datetime | None, created_by: str, description: str | None, id: str, linear_change_summary: fiftyone.management.snapshot.SampleChangeSummary | None, load_status: fiftyone.management.snapshot.DatasetSnapshotStatus, name: str, slug: str)#

Attributes:

`created_at`
`created_by`
`description`
`id`
`linear_change_summary`
`load_status`
`name`
`slug`

created_at: datetime | None#

created_by: str#

description: str | None#

id: str#

linear_change_summary: SampleChangeSummary | None#

load_status: DatasetSnapshotStatus#

name: str#

slug: str#

fiftyone.management.snapshot.archive_snapshot(dataset_name: str, snapshot_name: str) → None#

Archive snapshot to the configured cold storage location.

Note

Only users with MANAGE access can create a snapshot

Warning

Archiving a snapshot will make it unavailable for browsing to any user, even if they are currently using/browsing.

Examples:

import fiftyone as fo
import fiftyone.management as fom

snapshot_name = "v0.1"
# We don't use this regularly, archive it!
fom.archive_snapshot(dataset.name, snapshot_name)

fo.load_dataset(dataset.name, snapshot_name) # throws error, can't load!

Parameters:

dataset_name – the dataset name
snapshot_name – the snapshot name

fiftyone.management.snapshot.calculate_dataset_latest_changes_summary(dataset_name: str) → SampleChangeSummary#

Calculate change summary between recent snapshot and HEAD of dataset.

Examples:

import fiftyone.management as fom

old = fom.calculate_dataset_latest_changes_summary(dataset.name)
assert old == fom.get_dataset_latest_changes_summary(dataset.name)

dataset.delete_samples(dataset.take(5))

# Cached summary hasn't been updated
assert old == fom.get_dataset_latest_changes_summary(dataset.name)

new = fom.calculate_dataset_latest_changes_summary(dataset.name)
assert new.updated_at > changes.updated_at

Parameters:: dataset_name – the dataset name
Returns:: Change summary between most recent snapshot and HEAD of this dataset.

fiftyone.management.snapshot.create_snapshot(dataset_name: str, snapshot_name: str, description: str | None = None) → DatasetSnapshot#

Create and store a snapshot of the current state of dataset_name.

Snapshot name must be unique for the given dataset.

Note

Only users with MANAGE access can create a snapshot

Examples:

import fiftyone.management as fom

snapshot_name = "v0.1"
description = "Initial dataset snapshot"
fom.create_snapshot(dataset.name, snapshot_name, description)

Parameters:

dataset_name – the dataset name
snapshot_name – the name of the snapshot to create
description (None) – Optional description to attach to this snapshot

fiftyone.management.snapshot.delete_snapshot(dataset_name: str, snapshot_name: str)#

Delete snapshot snapshot_name from dataset dataset_name.

Note

Only users with MANAGE access can delete a snapshot.

Examples:

import fiftyone.management as fom

snapshot_name = "v0.1"
description = "Initial dataset snapshot"
fom.create_snapshot(dataset.name, snapshot_name, description)

# Some time later ...

fom.delete_snapshot(dataset, snapshot_name)

Parameters:

dataset_name – the dataset name
snapshot_name – the snapshot name

fiftyone.management.snapshot.get_dataset_latest_changes_summary(dataset_name: str) → SampleChangeSummary#

Gets change summary between most recent snapshot and HEAD of dataset

Note

This summary is not continuously computed, the result of this function may be stale. Use calculate_dataset_latest_changes_summary() to recalculate.

Examples:

import fiftyone.management as fom

fom.get_dataset_latest_changes_summary(dataset.name)

Parameters:

dataset_name – the dataset name

Returns:

Change summary between most recent snapshot and HEAD of this dataset.: Or None if no summary has been calculated yet.

Raises:

ValueError – if dataset doesn’t exist or no access

fiftyone.management.snapshot.get_snapshot_info(dataset_name: str, snapshot_name: str) → DatasetSnapshot | None#

Gets information about the specified dataset snapshot, or None: if snapshot_name doesn’t exist.

Examples:

import fiftyone.management as fom

dataset = "quickstart"
snapshot_name = "v0.1"

fom.get_snapshot_info(dataset.name, snapshot_name)

Parameters:

dataset_name – the dataset name
snapshot_name – the snapshot name

Raises:

ValueError – if dataset doesn’t exist or no access

fiftyone.management.snapshot.list_snapshots(dataset_name: str) → List[str]#

Returns a list of all snapshots of a dataset in order of creation.

Examples:

import fiftyone.management as fom

fom.list_snapshots(dataset.name)

Parameters:: dataset_name – the dataset name
Raises:: ValueError – if dataset doesn’t exist or no access
Returns:: a list of DatasetSnapshot instances

fiftyone.management.snapshot.revert_dataset_to_snapshot(dataset_name: str, snapshot_name: str)#

Revert dataset to a previous snapshot state.

Reverts the current (HEAD) state of dataset_name to a previous state encapsulated by the snapshot snapshot_name. All changes since then are lost. All snapshots created after this one will be deleted as well.

If you are attempting to view the dataset at the point of a snapshot but not completely revert, you can do so with:

snapshot = fo.load_dataset(dataset_name, snapshot=snapshot_name)

Note

Only users with MANAGE access can revert a dataset

Warning

This action is very destructive! All changes between snapshot_name and the current HEAD state of dataset_name will be destroyed! Including all snapshots created after snapshot_name.

Examples:

import fiftyone.management as fom

snapshot_name = "v0.1"
description = "Initial dataset snapshot"
fom.create_snapshot(dataset.name, snapshot_name, description)

# Oops we deleted everything!
dataset.delete_samples(dataset.values("id"))

# Phew!
fom.revert_dataset_to_snapshot(dataset.name, snapshot_name)
dataset.reload()
assert len(dataset) > 0

Parameters:

dataset_name – the dataset name
snapshot_name – the snapshot name

fiftyone.management.snapshot.unarchive_snapshot(dataset_name: str, snapshot_name: str) → None#

Unarchive snapshot from the configured cold storage location.

Examples:

import fiftyone as fo
import fiftyone.management as fom

snapshot_name = "v0.1"
description = "Initial dataset snapshot"

# We don't use this regularly, archive it!
fom.archive_snapshot(dataset.name, snapshot_name)
fo.load_dataset(dataset.name, snapshot_name) # throws error, can't load!

# Oops we need it now, unarchive it!
fom.unarchive_snapshot(dataset.name, snapshot_name)
fo.load_dataset(dataset.name, snapshot_name) # works now!

Parameters:

dataset_name – the dataset name
snapshot_name – the snapshot name

User management#

User management.

Copyright 2017-2025, Voxel51, Inc.
voxel51.com

Classes:

`UserRole`(value[, names, module, qualname, ...])	User role enum.
`User`(id, name, email, role)	User information dataclass.
`Invitation`(id, created_at, expires_at, ...)	Invitation dataclass.

Functions:

`delete_user`(user)	Deletes the given user.
`delete_user_invitation`(invitation)	Deletes/revokes a previously-sent invitation if it has not been accepted.
`get_user`(user)	Gets information about the specified user (if any).
`list_pending_invitations`()	Returns a list of pending user invitations.
`list_users`([verbose])	Returns a list of all users.
`send_user_invitation`(email, role)	Sends an email invitation to join your FiftyOne Enterprise organization.
`set_user_role`(user, role)	Sets the role of the given user.
`whoami`()	Returns information about the calling user.
`resolve_user_id`(user_or_id_or_email[, ...])	Resolves user ID - by looking up user by email if it has to

class fiftyone.management.users.UserRole(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

User role enum.

Attributes:

`ADMIN`
`MEMBER`
`COLLABORATOR`
`GUEST`

ADMIN = 'ADMIN'#

MEMBER = 'MEMBER'#

COLLABORATOR = 'COLLABORATOR'#

GUEST = 'GUEST'#

class fiftyone.management.users.User(id: str, name: str, email: str, role: UserRole)#

User information dataclass.

Attributes:

`id`
`name`
`email`
`role`

id: str#

name: str#

email: str#

role: UserRole#

class fiftyone.management.users.Invitation(id: str, created_at: datetime, expires_at: datetime, invitee_email: str, invitee_role: UserRole, url: str)#

Invitation dataclass.

Attributes:

`id`
`created_at`
`expires_at`
`invitee_email`
`invitee_role`
`url`

id: str#

created_at: datetime#

expires_at: datetime#

invitee_email: str#

invitee_role: UserRole#

url: str#

fiftyone.management.users.delete_user(user: str | User) → None#

Deletes the given user.

Note

Only admins can perform this action.

Warning

This action is irreversible! Once deleted, the user will have to be re-invited to the organization to have access again.

Examples:

import fiftyone.management as fom

delete_user = "guest@company.com"

fom.delete_user(delete_user)

assert fom.get_user(delete_user) is None

Parameters:: user – a user ID, email string, or User instance

fiftyone.management.users.delete_user_invitation(invitation: str) → None#

Deletes/revokes a previously-sent invitation if it has not been accepted.

Note

Only admins can perform this action.

Examples:

import fiftyone.management as fom

new_guest = "guest@company.com"

invite_id = fom.send_user_invitation(new_guest, fom.GUEST)

# Delete by invitation ID
fom.delete_user_invitation(invite_id)

# Delete by user email
fom.delete_user_invitation(new_guest)

pending = fom.list_pending_invitations()
assert not any(p.id == invite_id for p in pending)

Parameters:: invitation – an invitation ID as returned by send_user_invitation(), or email address

fiftyone.management.users.get_user(user: str) → User | None#

Gets information about the specified user (if any).

Note

Only admins can retrieve information about other users.

Examples:

import fiftyone.management as fom

known_user = "member@company.com"
user = fom.get_user(known_user)
assert user.email == known_user

unknown_user = "unknown@company.com"
assert fom.get_user(unknown_user) is None

Parameters:: user – a user ID or email string
Returns:: User, or None if no such user is found

fiftyone.management.users.list_pending_invitations() → List[Invitation]#

Returns a list of pending user invitations.

Note

Only admins can retrieve this information.

Examples:

import fiftyone.management as fom

fom.list_pending_invitations()

Returns:: a list of Invitation instances

fiftyone.management.users.list_users(verbose=True) → List[User] | List[str]#

Returns a list of all users.

Note

Only admins can retrieve this information.

Examples:

import fiftyone.management as fom

fom.list_users()

Parameters:: verbose (True) – if True, return a list of User instances; if False, return a list of user emails
Returns:: a list of User instances

fiftyone.management.users.send_user_invitation(email: str, role: UserRole) → str#

Sends an email invitation to join your FiftyOne Enterprise organization.

Note

Only admins can perform this action.

Examples:

import fiftyone.management as fom

new_guest = "guest@company.com"

invite_id = fom.send_user_invitation(new_guest, fom.GUEST)

pending = fom.list_pending_invitations()
assert any(p.invitee_email == new_guest for p in pending)

Parameters:

email – the email address
role – the UserRole to grant the new user

Returns:

the invitation ID string

fiftyone.management.users.set_user_role(user: str | User, role: UserRole) → None#

Sets the role of the given user.

Note

Only admins can perform this action.

Examples:

import fiftyone.management as fom

user = "user@company.com"

#1.a set role from email
fom.set_user_role(user, fom.MEMBER)

#1.b set role from user instance
user_obj = fom.get_user(user_obj)
fom.set_user_role(user_obj, fom.MEMBER)

assert fom.get_user(user).role == fom.MEMBER

Parameters:

user – a user ID, email string, or User instance
role – the UserRole to set

fiftyone.management.users.whoami() → User#

Returns information about the calling user.

Examples:

import fiftyone.management as fom

me = fom.whoami()

assert fom.get_user(me.id) == me

Returns:: User

fiftyone.management.users.resolve_user_id(user_or_id_or_email: str | User | None, nullable: bool = False, pass_unknown_email: bool = False) → str | None#: Resolves user ID - by looking up user by email if it has to

Group management#

Group management.

Copyright 2017-2025, Voxel51, Inc.
voxel51.com

Classes:

UserGroup(id, name, description, users)

User Group information dataclass.

Functions:

`add_users_to_group`(user_group, users[, ...])	Adds users to the given group.
`create_user_group`(name[, description, users])	Creates a new user group.
`delete_user_group`(user_group)	Deletes the given group.
`get_user_group`(user_group)	Gets information about the specified group (if any).
`list_user_groups_for_user`(user[, verbose])	Gets all user groups for the given user.
`list_user_groups`([num_groups, verbose])	Returns a list of all user groups.
`remove_users_from_group`(user_group, users[, ...])	Removes users from the given group.
`update_user_group`(user_group[, name, ...])	Updates the given group.
`resolve_user_group_id`(group_or_id_or_name)	Resolves group ID - by looking up group by name if it has to

class fiftyone.management.user_groups.UserGroup(id: str, name: str, description: str | None, users: List[User] | None)#

User Group information dataclass.

Attributes:

`id`
`name`
`description`
`users`

id: str#

name: str#

description: str | None#

users: List[User] | None#

fiftyone.management.user_groups.add_users_to_group(user_group: str, users: List[Any] | str, resolved_users: bool = False) → UserGroup#

Adds users to the given group.

Note

Only admins can perform this action.

Examples:

import fiftyone.management as fom

group_id = "group id"
user_ids = ["user id 1", "user id 2"]

fom.add_users_to_group(user_group=group_id, user_ids=user_ids)

Parameters:

user_group – a group ID, name string, or Group instance
users (None) – list of users (email or ID strings or User instances or dictionary objects with valid fields) or a single user string/obj
resolved_users (False) – If True, the user_ids are already resolved/validated

fiftyone.management.user_groups.create_user_group(name: str, description: str | None = None, users: List[str | User] | None = None) → UserGroup#

Creates a new user group.

Note

Only admins can perform this action.

Examples:

import fiftyone.management as fom

group_name = "Name"
group_description = "Description"
fom.add_user_group(name=group_name, description=group_description)

assert fom.get_user_group(group_name) is not None

Parameters:

name – group name, string
description (None) – optional group description, string
users (None) – optional list of user_ids, names or Users instance

fiftyone.management.user_groups.delete_user_group(user_group: str | UserGroup) → None#

Deletes the given group.

Note

Only admins can perform this action.

Warning

This action is irreversible!

Examples:

import fiftyone.management as fom

group_name = "Group Name"
fom.delete_user_group(group_name)

assert fom.get_user_group(group_name) is None

Parameters:: user_group – a group ID, name string, or Group instance

fiftyone.management.user_groups.get_user_group(user_group: str) → UserGroup | None#

Gets information about the specified group (if any).

Note

Only admins can retrieve information about user groups.

Examples:

import fiftyone.management as fom

group_name = "Group Name"
group = fom.get_user_group(group_name)
assert group.name == group_name

unknown_group = "Unknown Group"
assert fom.get_user_group(unknown_group) is None

Parameters:: user_group – a group ID or name string
Returns:: Group, or None if no such group is found

fiftyone.management.user_groups.list_user_groups_for_user(user: str | dict | User, verbose=False) → List[dict]#

Gets all user groups for the given user.

If the user_id does not exist, an empty list is returned.

if the email address is incorrect, an exception is raised.

If there is no group associated with the user, an empty list is returned.

Note

Only admins can retrieve this information.

Examples:

import fiftyone.management as fom

user_id = "user id"
fom.list_user_groups_for_user(user_id)

Parameters:

user – a user ID or email string, or User instance
verbose (True) – If True, returns the list of groups, otherwise return the list of group names

Returns:

a list of dictionaries containing user group information or a list of: group names

fiftyone.management.user_groups.list_user_groups(num_groups: int = 100, verbose=False) → List[UserGroup] | List[str]#

Returns a list of all user groups.

Note

Only admins can retrieve this information.

Examples:

import fiftyone.management as fom

fom.list_user_groups()

Parameters:

num_groups (100) – The number of user groups to fetch
verbose (False) – If True, returns the list of groups, otherwise return
names (the list of group)

Returns:

a list of Group instances or a list of group names

fiftyone.management.user_groups.remove_users_from_group(user_group: str, users: List[Any] | str, resolved_users: bool = False) → UserGroup#

Removes users from the given group.

Note

Only admins can perform this action.

Examples:

import fiftyone.management as fom

user_group = "group id"
user_ids = ["user id 1", "user id 2"]

fom.remove_users_from_group(user_group=group_id, user_ids=user_ids)

Parameters:

user_group – a group ID, name string, or Group instance
users (None) – list of users (email or ID strings or User instances or dictionary objects with valid fields) or a single user string/obj
resolved_users (False) – If True, the user_ids are already resolved/validated

fiftyone.management.user_groups.update_user_group(user_group: str, name: str | None = None, description: str | None = None, users: List[str | UserGroup] | None = None) → UserGroup#

Updates the given group.

Note

Only admins can perform this action.

Examples:

import fiftyone.management as fom

group_id = "group id"
group_name = "New Name"
fom.update_user_group(user_group=group_id, name=group_name)

assert fom.get_user_group(group_name) is not None

Parameters:

user_group – a group ID, name string, or Group instance
name (None) – group name, string
description (None) – group description, string
users (None) – list of user id, name string or User instance. Existing users not in this list will be removed.

fiftyone.management.user_groups.resolve_user_group_id(group_or_id_or_name: str | UserGroup | None | dict) → str#: Resolves group ID - by looking up group by name if it has to