Skip to main content

Python SDK Reference

note

Please note that only AnyscaleSDK and imports under anyscale.sdk are considered public.

AnyscaleSDK

The AnyscaleSDK class must be constructed in order to make calls to the SDK. This class allows you to create an authenticated client in which to use the SDK.

ParamTypeDescription
auth_tokenOptional StringAuthentication token used to verify you have permissions to access Anyscale. If not provided, we will default to the credentials set for your current user. Credentials can be set by following the instructions on this page: https://console.anyscale.com/credentials

Example

from anyscale import AnyscaleSDK

sdk = AnyscaleSDK()

Utility Functions

build_cluster_environment

Creates a new Cluster Environment and waits for build to complete.

If a Cluster Environment with the same name already exists, this will create an updated build of that environment.

Returns the newly created ClusterEnvironmentBuild object.

Raises an Exception if building Cluster Environment fails or times out.

ParamTypeDescription
create_cluster_environmentCreateClusterEnvironmentCreateClusterEnvironment object
poll_rate_secondsOptional Integerseconds to wait when polling build operation status; defaults to 15
timeout_secondsOptional Integermaximum number of seconds to wait for build operation to complete before timing out; defaults to no timeout

Example

from anyscale.sdk.anyscale_client.models.create_cluster_environment import (
CreateClusterEnvironment,
)
from anyscale import AnyscaleSDK

sdk = AnyscaleSDK(auth_token="sss_YourAuthToken")

create_cluster_environment = CreateClusterEnvironment(
name="my-cluster-environment",
config_json={"base_image": "anyscale/ray:1.4.1-py37"}
)

cluster_environment_build = sdk.build_cluster_environment(
create_cluster_environment=create_cluster_environment
)

print(f"Cluster Environment built successfully: {cluster_environment_build}")

fetch_actor_logs

Retrieves logs for an Actor.

This function may take several minutes if the Cluster this Actor ran on has been terminated.

Returns the log output as a string.

Raises an Exception if fetching logs fails.

ParamTypeDescription
actor_idStringID of the Actor

Example

from anyscale.sdk.anyscale_client.models.create_cluster_environment import (
CreateClusterEnvironment,
)
from anyscale import AnyscaleSDK

sdk = AnyscaleSDK(auth_token="sss_YourAuthToken")

actor_logs = sdk.fetch_actor_logs(actor_id="actor_id")

print(actor_logs)

fetch_job_logs

Retrieves logs for a Job.

This function may take several minutes if the Cluster this Job ran on has been terminated.

Returns the log output as a string.

Raises an Exception if fetching logs fails.

ParamTypeDescription
job_idStringID of the Job

Example

from anyscale import AnyscaleSDK

sdk = AnyscaleSDK(auth_token="sss_YourAuthToken")

job_logs = sdk.fetch_job_logs(job_id="job_id")

print(job_logs)

fetch_production_job_logs

Retrieves logs for a Production Job.

This function may take several minutes if the Cluster this Production Job ran on has been terminated.

Returns the log output as a string.

Raises an Exception if fetching logs fails.

ParamTypeDescription
job_idStringID of the Job

Example

from anyscale import AnyscaleSDK

sdk = AnyscaleSDK(auth_token="sss_YourAuthToken")

job_logs = sdk.fetch_production_job_logs(job_id="production_job_id")

print(job_logs)

launch_cluster

Starts a Cluster in the specified Project.

If a Cluster with the specified name already exists, we will update that Cluster. Otherwise, a new Cluster will be created.

Returns the started Cluster object.

Raises an Exception if starting Cluster fails or times out.

ParamTypeDescription
project_idStringID of the Project the Cluster belongs to
cluster_nameStringName of the Cluster
cluster_environment_build_idStringID of the Cluster Environment Build to start this Cluster with
cluster_compute_idOptional StringID of the Cluster Compute to start this Cluster with
cluster_compute_configOptional DictOne-off Cluster Compute that this Cluster will use, with same fields as ClusterComputeConfig
poll_rate_secondsOptional Integerseconds to wait when polling cluster operation status; defaults to 15
idle_timeout_minutesOptional IntegerIdle timeout (in minutes), after which the Cluster is terminated; Defaults to 120 minutes.
timeout_secondsOptional Integermaximum number of seconds to wait for cluster operation to complete before timing out; defaults to no timeout

Example

from anyscale import AnyscaleSDK

sdk = AnyscaleSDK(auth_token="sss_YourAuthToken")

cluster = sdk.launch_cluster(
project_id="project_id",
cluster_name="my-cluster",
cluster_environment_build_id="cluster_environment_build_id",
cluster_compute_id="cluster_compute_id")

print(f"Cluster started successfully: {cluster}")

launch_cluster_with_new_cluster_environment

Builds a new Cluster Environment, then starts a Cluster in the specified Project with the new build.

If a Cluster with the specified name already exists, we will update that Cluster. Otherwise, a new Cluster will be created.

Returns the started Cluster object.

Raises an Exception if building Cluster Environment fails or starting the Cluster fails.

ParamTypeDescription
project_idStringID of the Project the Cluster belongs to
cluster_nameStringName of the Cluster
create_cluster_environmentCreateClusterEnvironmentCreateClusterEnvironment object
cluster_compute_idOptional StringCluster Compute to start this Cluster with
cluster_compute_configOptional DictOne-off Cluster Compute that this Cluster will use, with same fields as ClusterComputeConfig
poll_rate_secondsOptional Integerseconds to wait when polling operation status; defaults to 15
timeout_secondsOptional Integermaximum number of seconds to wait for operations to complete before timing out; defaults to no timeout

Example

from anyscale import AnyscaleSDK
from anyscale.sdk.anyscale_client.models.create_cluster_environment import (
CreateClusterEnvironment,
)

sdk = AnyscaleSDK(auth_token="sss_YourAuthToken")

create_cluster_environment = CreateClusterEnvironment(
name="my-cluster-environment",
config_json={"base_image": "anyscale/ray:1.4.1-py37"}
)

cluster = sdk.launch_cluster_with_new_cluster_environment(
project_id="project_id",
cluster_name="my-cluster",
create_cluster_environment=create_cluster_environment,
cluster_compute_id="cluster_compute_id",
)

print(f"Cluster started successfully: {cluster}")
info

The OpenAPI schemas for types below can be found at the Anyscale OpenAPI Documentation

All of the following functions are synchronous by default. To make an asynchronous HTTP request, please pass async_req=True. The return value for the asynchronous calls is a thread.

thread = api.create_cloud(create_cloud, async_req=True)
result = thread.get()

Clouds

create_cloud

Creates a Cloud.

Parameters

NameTypeDescriptionNotes
create_cloudCreateCloud

Returns CloudResponse

delete_cloud

Deletes a Cloud. Will delete all clusters that are using this cloud. If any of those clusters are not terminated, this call will fail.

Parameters

NameTypeDescriptionNotes
cloud_idstrID of the Cloud to delete.Defaults to null

Returns void (empty response body)

get_cloud

Retrieves a Cloud.

Parameters

NameTypeDescriptionNotes
cloud_idstrID of the Cloud to retrieve.Defaults to null

Returns CloudResponse

get_default_cloud

Retrieves the default cloud for the logged in user. First prefers the default cloud set by the user's org, then the last used cloud.

Parameters This function does not have any parameters.

Returns CloudResponse

search_clouds

Searches for all accessible Clouds that satisfies the query.

Parameters

NameTypeDescriptionNotes
clouds_queryCloudsQuery

Returns CloudListResponse

update_cloud

Updates a Cloud.

Parameters

NameTypeDescriptionNotes
cloud_idstrID of the Cloud to update.Defaults to null
update_cloudUpdateCloud

Returns CloudResponse

Cluster Computes

create_cluster_compute

Creates a Cluster Compute. If the specified compute config is anonymous, returns an existing compute config if an anonymous one exists with the same config.

Parameters

NameTypeDescriptionNotes
create_cluster_computeCreateClusterCompute

Returns ClustercomputeResponse

delete_cluster_compute

Deletes a Cluster Compute.

Parameters

NameTypeDescriptionNotes
cluster_compute_idstrID of the Cluster Compute to delete.Defaults to null

Returns void (empty response body)

get_cluster_compute

Retrieves a Cluster Compute.

Parameters

NameTypeDescriptionNotes
cluster_compute_idstrID of the Cluster Compute to retrieve.Defaults to null

Returns ClustercomputeResponse

get_default_cluster_compute

Returns a default cluster compute that can be used with a given cloud.

Parameters

NameTypeDescriptionNotes
cloud_idoptional strThe cloud id whose default cluster compute you want to fetch. If None, will use the default cloud.Defaults to null

Returns ClustercomputeResponse

search_cluster_computes

Lists all Cluster Computes the user has access to, matching the input query.

Parameters

NameTypeDescriptionNotes
cluster_computes_queryClusterComputesQuery

Returns ClustercomputeListResponse

Cluster Environment Build Operations

get_cluster_environment_build_operation

Retrieves a Cluster Environment Build Operation.

Parameters

NameTypeDescriptionNotes
cluster_environment_build_operation_idstrID of the Cluster Environment Build Operation to retrieve.Defaults to null

Returns ClusterenvironmentbuildoperationResponse

Cluster Environment Builds

create_byod_cluster_environment_build

Creates and starts a BYOD Cluster Environment Build.

Parameters

NameTypeDescriptionNotes
create_byod_cluster_environment_buildCreateBYODClusterEnvironmentBuild

Returns ClusterenvironmentbuildoperationResponse

create_cluster_environment_build

Creates and starts a Cluster Environment Build. This is a long running operation.

Parameters

NameTypeDescriptionNotes
create_cluster_environment_buildCreateClusterEnvironmentBuild

Returns ClusterenvironmentbuildoperationResponse

find_cluster_environment_build_by_identifier

Looks for a cluster environment build given a cluster environment identifier. Identifiers are in the format my-cluster-env:1

Parameters

NameTypeDescriptionNotes
identifierstrIdentifier of the cluster env to look for. Identifiers are in the format my-cluster-env:1Defaults to null

Returns ClusterenvironmentbuildResponse

get_cluster_environment_build

Retrieves a Cluster Environment Build.

Parameters

NameTypeDescriptionNotes
cluster_environment_build_idstrID of the Cluster Environment Build to retrieve.Defaults to null

Returns ClusterenvironmentbuildResponse

get_cluster_environment_build_logs

Retrieves logs for a Cluster Environment Build.

Parameters

NameTypeDescriptionNotes
cluster_environment_build_idstrID of the Cluster Environment Build to retrieve logs for.Defaults to null

Returns ClusterenvironmentbuildlogresponseResponse

get_default_cluster_environment_build

Retrieves a default cluster environment with the preferred attributes.

Parameters

NameTypeDescriptionNotes
python_versionPythonVersionPython version for the cluster environmentDefaults to null
ray_versionstrRay version to use for this cluster environment. Should match a version string found in the ray version history on pypi. See here for full list: https://pypi.org/project/ray/#historyDefaults to null

Returns ClusterenvironmentbuildResponse

list_cluster_environment_builds

Lists all Cluster Environment Builds belonging to an Cluster Environment.

Parameters

NameTypeDescriptionNotes
cluster_environment_idstrID of the Cluster Environment to list builds for.Defaults to null
descoptional boolOrders the list of builds from latest to oldest.Defaults to false
paging_tokenoptional strDefaults to null
countoptional intDefaults to 10

Returns ClusterenvironmentbuildListResponse

Cluster Environments

create_byod_cluster_environment

Creates a BYOD Cluster Environment.

Parameters

NameTypeDescriptionNotes
create_byod_cluster_environmentCreateBYODClusterEnvironment

Returns ClusterenvironmentResponse

create_cluster_environment

Creates a Cluster Environment.

Parameters

NameTypeDescriptionNotes
create_cluster_environmentCreateClusterEnvironment

Returns ClusterenvironmentResponse

delete_cluster_environment

Deletes a Cluster Environment.

Parameters

NameTypeDescriptionNotes
cluster_config_idstrID of the Cluster Environment to delete.Defaults to null

Returns void (empty response body)

get_cluster_environment

Retrieves a Cluster Environment.

Parameters

NameTypeDescriptionNotes
cluster_environment_idstrID of the Cluster Environment to retrieve.Defaults to null

Returns ClusterenvironmentResponse

search_cluster_environments

Lists all Cluster Environments that the logged in user has permissions to access.

Parameters

NameTypeDescriptionNotes
cluster_environments_queryClusterEnvironmentsQuery

Returns ClusterenvironmentListResponse

Cluster Operations

get_cluster_operation

Retrieves a Cluster Operation.

Parameters

NameTypeDescriptionNotes
cluster_operation_idstrID of the Cluster Operation to retrieve.Defaults to null

Returns ClusteroperationResponse

Clusters

archive_cluster

Archives the cluster. It is a no-op if the cluster is already archived.

Parameters

NameTypeDescriptionNotes
cluster_idstrDefaults to null

Returns void (empty response body)

create_cluster

Creates a Cluster.

Parameters

NameTypeDescriptionNotes
create_clusterCreateCluster

Returns ClusterResponse

delete_cluster

Deletes a Cluster.

Parameters

NameTypeDescriptionNotes
cluster_idstrID of the Cluster to delete.Defaults to null

Returns void (empty response body)

get_cluster

Retrieves a Cluster.

Parameters

NameTypeDescriptionNotes
cluster_idstrID of the Cluster to retreive.Defaults to null

Returns ClusterResponse

search_clusters

Searches for all Clusters the user has access to that satisfies the query.

Parameters

NameTypeDescriptionNotes
clusters_queryClustersQuery

Returns ClusterListResponse

start_cluster

Initializes workflow to transition the Cluster into the Running state. This is a long running operation. Clients will need to poll the operation's status to determine completion. The options parameter is DEPRECATED.

Parameters

NameTypeDescriptionNotes
cluster_idstrID of the Cluster to start.Defaults to null
start_cluster_optionsStartClusterOptions

Returns ClusteroperationResponse

terminate_cluster

Initializes workflow to transition the Cluster into the Terminated state. This is a long running operation. Clients will need to poll the operation's status to determine completion.

Parameters

NameTypeDescriptionNotes
cluster_idstrID of the Cluster to terminate.Defaults to null
terminate_cluster_optionsTerminateClusterOptions

Returns ClusteroperationResponse

update_cluster

Updates a Cluster.

Parameters

NameTypeDescriptionNotes
cluster_idstrID of the Cluster to update.Defaults to null
update_clusterUpdateCluster

Returns ClusterResponse

Jobs

search_jobs

DEPRECATED: This API is now deprecated. Use list_production_jobs instead.

Parameters

NameTypeDescriptionNotes
jobs_queryJobsQuery

Returns JobListResponse

Logs

get_job_logs_download

Parameters

NameTypeDescriptionNotes
job_idstrDefaults to null
all_logsoptional boolWhether to grab all logs.Defaults to true

Returns LogdownloadresultResponse

get_job_logs_stream

Parameters

NameTypeDescriptionNotes
job_idstrDefaults to null

Returns LogstreamResponse

Organizations

get_organization_temporary_object_storage_credentials

Retrieves temporary object storage config and credentials scoped to an organization and region.

Parameters

NameTypeDescriptionNotes
organization_idstrDefaults to null
regionstrDefaults to null

Returns ObjectstorageconfigResponse

partial_update_organization

Update an organization's requirement for Single Sign On (SSO). If SSO is required for an organization, SSO will be the only way to log in to it.

Parameters

NameTypeDescriptionNotes
organization_idstrID of the Organization to update.Defaults to null
update_organizationUpdateOrganization

Returns OrganizationResponse

Production Jobs

create_job

Create an Production Job

Parameters

NameTypeDescriptionNotes
create_production_jobCreateProductionJob

Returns ProductionjobResponse

get_production_job

Get an Production Job

Parameters

NameTypeDescriptionNotes
production_job_idstrDefaults to null

Returns ProductionjobResponse

get_session_for_job

Get Session for Production Job

Parameters

NameTypeDescriptionNotes
production_job_idstrDefaults to null

Returns SessionResponse

list_production_jobs

Parameters

NameTypeDescriptionNotes
project_idoptional strproject_id to filter byDefaults to null
nameoptional strname to filter byDefaults to null
state_filterList[HaJobStates]A list of session states to filter byDefaults to []
creator_idoptional strfilter by creator idDefaults to null
paging_tokenoptional strDefaults to null
countoptional intDefaults to null

Returns ProductionjobListResponse

terminate_job

Terminate an Production Job

Parameters

NameTypeDescriptionNotes
production_job_idstrDefaults to null

Returns ProductionjobResponse

Projects

create_project

Creates a Project.

Parameters

NameTypeDescriptionNotes
create_projectCreateProject

Returns ProjectResponse

delete_project

Deletes a Project.

Parameters

NameTypeDescriptionNotes
project_idstrID of the Project to delete.Defaults to null

Returns void (empty response body)

get_default_project

Retrieves the default project.

Parameters

NameTypeDescriptionNotes
parent_cloud_idoptional strCloud to fetch this default project for. This is only required if cloud isolation is enabled.Defaults to null

Returns ProjectResponse

get_project

Retrieves a Project.

Parameters

NameTypeDescriptionNotes
project_idstrID of the Project to retrieve.Defaults to null

Returns ProjectResponse

search_projects

Searches for all Projects the user has access to that satisfies the query.

Parameters

NameTypeDescriptionNotes
projects_queryProjectsQuery

Returns ProjectListResponse

update_project

Updates a Project.

Parameters

NameTypeDescriptionNotes
project_idstrID of the Project to update.Defaults to null
update_projectUpdateProject

Returns ProjectResponse

Runtime Environments

get_runtime_environment

Retrieves a Runtime Environment.

Parameters

NameTypeDescriptionNotes
runtime_environment_idstrID of the Runtime Environment to retrieve.Defaults to null

Returns RuntimeenvironmentResponse

Schedules

create_or_update_schedule

Create or update a Schedule

Parameters

NameTypeDescriptionNotes
create_scheduleCreateSchedule

Returns ScheduleapimodelResponse

get_schedule

Get Schedules

Parameters

NameTypeDescriptionNotes
schedule_idstrDefaults to null

Returns ScheduleapimodelResponse

list_schedules

List Schedules

Parameters

NameTypeDescriptionNotes
project_idoptional strproject_id to filter byDefaults to null
nameoptional strname to filter byDefaults to null
creator_idoptional strfilter by creator idDefaults to null

Returns ScheduleapimodelListResponse

pause_schedule

Pause a Schedule

Parameters

NameTypeDescriptionNotes
schedule_idstrDefaults to null
pause_schedulePauseSchedule

Returns ScheduleapimodelResponse

run_schedule

Run a Schedule manually

Parameters

NameTypeDescriptionNotes
schedule_idstrDefaults to null

Returns ProductionjobResponse

Services

get_service

Get a Service

Parameters

NameTypeDescriptionNotes
service_idstrDefaults to null

Returns ServicemodelResponse

list_services

Parameters

NameTypeDescriptionNotes
project_idoptional strproject_id to filter byDefaults to null
nameoptional strname to filter byDefaults to null
state_filterList[ServiceEventCurrentState]A list of Service states to filter byDefaults to []
creator_idoptional strcreator_id to filter byDefaults to null
cloud_idoptional strcloud_id to filter byDefaults to null
sort_fieldServiceSortFieldIf absent, the default sorting order is 1. status (active first).2. Last updated at (desc). 3. Name (asc).Defaults to null
sort_orderSortOrderIf sort_field is absent, this field is ignored.If absent, this field defaults to ascending.Defaults to null
paging_tokenoptional strDefaults to null
countoptional intDefaults to null

Returns ServicemodelListResponse

rollback_service

Rollback a Service

Parameters

NameTypeDescriptionNotes
service_idstrDefaults to null
rollback_service_modelRollbackServiceModel

Returns ServicemodelResponse

rollout_service

Rollout a service

Parameters

NameTypeDescriptionNotes
apply_service_modelApplyServiceModel

Returns ServicemodelResponse

terminate_service

Terminate a Service

Parameters

NameTypeDescriptionNotes
service_idstrDefaults to null

Returns ServicemodelResponse

Session Commands

create_session_command

DEPRECATED: This API is now deprecated and will not be supported in Anyscale 2.0

Parameters

NameTypeDescriptionNotes
create_session_commandCreateSessionCommand

Returns SessioncommandResponse

get_session_command

Retrieves a session command with ID.

Parameters

NameTypeDescriptionNotes
session_command_idstrID of the Session Command to retrieve.Defaults to null

Returns SessioncommandResponse

list_session_commands

Retrieves a list of commands that were created on the Session.

Parameters

NameTypeDescriptionNotes
session_idstrID of the Session to list Commands for.Defaults to null
paging_tokenoptional strDefaults to null
countoptional intDefaults to 10

Returns SessioncommandListResponse

Session Events

get_session_event_log

Retrieves a session's event log.

Parameters

NameTypeDescriptionNotes
session_idstrID of the Session to retrieve event logs for.Defaults to null
beforeoptional datetimeFilters events occurring before this datetime.Defaults to null
afteroptional datetimeFilters events occurring after this datetime.Defaults to null
event_typesList[SessionEventTypes]Filters events to these types.Defaults to null
log_level_typesList[LogLevelTypes]Filters logs to these leves.Defaults to null
paging_tokenoptional strDefaults to null
countoptional intDefaults to 20

Returns SessioneventListResponse

Sso Configs

upsert_sso_config

Create or update the single sign on (SSO) configuration for your organization.

Parameters

NameTypeDescriptionNotes
create_sso_configCreateSSOConfig

Returns SsoconfigResponse

upsert_test_sso_config

Create or update the test single sign on (SSO) configuration for your organization.

Parameters

NameTypeDescriptionNotes
create_sso_configCreateSSOConfig

Returns SsoconfigResponse