Jump to

• Request
• Response

Get clusters in a workspace

get

/20260430/aiDataPlatforms/{aiDataPlatformId}/workspaces/{workspaceKey}/clusters

Returns a list of all clusters in a given workspace.

Request

Path Parameters

• aiDataPlatformId(required): string
  The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the AI Data Platform (Data Lake) instance.
• workspaceKey(required): string
  The key of the Workspace

Query Parameters

• displayName: string
  Minimum Length: 1

  Maximum Length: 255

  A filter to return only resources that match the given display name exactly.
• displayNameContains: string
  A filter to return only resources that have a display name containing the text provided.
• limit: integer
  Minimum Value: 1

  Maximum Value: 1000

  For list pagination. The maximum number of results per page, or items to return in a paginated "List" call. For important details about how pagination works, see [List Pagination](/iaas/Content/API/Concepts/usingapi.htm#nine).

  Default Value: 100
• page: string
  Minimum Length: 1

  For list pagination. The value of the opc-next-page response header from the previous "List" call. For important details about how pagination works, see [List Pagination](/iaas/Content/API/Concepts/usingapi.htm#nine).
• sortBy: string
  The field to sort by. You can provide only one sort order. Default order for `timeCreated` is descending. Default order for `displayName` is ascending.

  Default Value: timeCreated

  Allowed Values: [ "timeCreated", "displayName" ]
• sortOrder: string
  The sort order to use, either ascending (`ASC`) or descending (`DESC`).

  Allowed Values: [ "ASC", "DESC" ]
• state: string
  A filter to return only resources that match the given lifecycle state. The state value is case-insensitive.
• type: string
  Cluster type. When the filter is not provided list shows all type of cluster - USER else it show only cluster of type chosen. Only clusters of type USER are attachable to a workspace notebook.

Header Parameters

• opc-request-id: string
  Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID. The only valid characters for request IDs are letters, numbers, underscore, and dash.

Back to Top

Response

Supported Media Types

• application/json

200 Response

Successful operation. List of all clusters in workspace is retrieved.

Headers

• opc-next-page: string
  For list pagination. When this header appears in the response, additional pages of results remain. For important details about how pagination works, see [List Pagination](/iaas/Content/API/Concepts/usingapi.htm#nine).
• opc-request-id: string
  Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : ClusterCollection

Type: object

Results of a cluster list.

Show Source

• items(required): array items
  List of Clusters.

{
    "type":"object",
    "description":"Results of a cluster list.",
    "required":[
        "items"
    ],
    "properties":{
        "items":{
            "description":"List of Clusters.",
            "type":"array",
            "items":{
                "$ref":"#/definitions/ClusterSummary"
            }
        }
    }
}

Nested Schema : items

Type: array

List of Clusters.

Show Source

• Array of: object ClusterSummary
  Summary information about a workspace cluster.

{
    "description":"List of Clusters.",
    "type":"array",
    "items":{
        "$ref":"#/definitions/ClusterSummary"
    }
}

Nested Schema : ClusterSummary

Type: object

Summary information about a workspace cluster.

Show Source

• activeClusterResources: object ActiveClusterResources
  Active resources of a cluster.
• attachedAgentFlowCount: integer
  Default Value: oracle.doceng.json.BetterJsonNull@5e8f9e2d

  Count of agent flow attached to a specific cluster.
• attachedNotebooks: array attachedNotebooks
  List of notebooks attached to a specific cluster.
• attachedSessions: array attachedSessions
  List of sessions attached to a specific cluster.
• clusterRuntimeConfig: object ClusterRuntimeConfig
  Discriminator: type

  Cluster runtime configurations.
• createdBy: string
  OCID of the user who created this record.
• createdByName: string
  Name of the user who created this record.
• description: string
  Minimum Length: 1

  Maximum Length: 400

  Cluster description.
• displayName(required): string
  Cluster name.
• driverConfig: object DriverConfig
  Driver configuration.
• key(required): string
  Cluster key.
• state(required): string
  The current state of the cluster.
• stateDetails: string
  A message that describes the current state of the workspace cluster in more detail. For example, can be used to provide actionable information for a resource in the Failed state.
• stoppedBy: string
  OCID of the user who stopped the cluster. Value will be 'SYSTEM' if it was auto stopped.
• stoppedByName: string
  Name of the user who stopped the cluster. Value will be 'SYSTEM' if it was auto stopped.
• timeCreated(required): string(date-time)
  Date and time the cluster was created.
• timeUpdated: string(date-time)
  Date and time the cluster was updated.
• type(required): string
  Allowed Values: [ "USER", "AGENT_FLOW_COMPUTE" ]

  ClusterType
• updatedBy: string
  OCID of the user who updated this record.
• updatedByName: string
  Name of the user who updated this record.
• workerConfig: object WorkerConfig
  Worker configuration.

{
    "description":"Summary information about a workspace cluster.",
    "type":"object",
    "required":[
        "key",
        "state",
        "type",
        "timeCreated",
        "displayName"
    ],
    "properties":{
        "key":{
            "description":"Cluster key.",
            "type":"string"
        },
        "displayName":{
            "description":"Cluster name.",
            "type":"string"
        },
        "description":{
            "description":"Cluster description.",
            "type":"string",
            "minLength":1,
            "maxLength":400
        },
        "type":{
            "type":"string",
            "description":"ClusterType",
            "x-obmcs-top-level-enum":"#/definitions/ClusterType",
            "enum":[
                "USER",
                "AGENT_FLOW_COMPUTE"
            ]
        },
        "timeCreated":{
            "description":"Date and time the cluster was created.",
            "type":"string",
            "format":"date-time"
        },
        "timeUpdated":{
            "description":"Date and time the cluster was updated.",
            "type":"string",
            "format":"date-time"
        },
        "state":{
            "type":"string",
            "description":"The current state of the cluster.",
            "x-obmcs-enumref":"#/definitions/Cluster/state"
        },
        "stateDetails":{
            "description":"A message that describes the current state of the workspace cluster in more detail. For example, can be used to provide actionable information for a resource in the Failed state.",
            "type":"string"
        },
        "createdBy":{
            "description":"OCID of the user who created this record.",
            "type":"string"
        },
        "createdByName":{
            "description":"Name of the user who created this record.",
            "type":"string"
        },
        "updatedBy":{
            "description":"OCID of the user who updated this record.",
            "type":"string"
        },
        "updatedByName":{
            "description":"Name of the user who updated this record.",
            "type":"string"
        },
        "stoppedBy":{
            "description":"OCID of the user who stopped the cluster. Value will be 'SYSTEM' if it was auto stopped.",
            "type":"string"
        },
        "stoppedByName":{
            "description":"Name of the user who stopped the cluster. Value will be 'SYSTEM' if it was auto stopped.",
            "type":"string"
        },
        "clusterRuntimeConfig":{
            "$ref":"#/definitions/ClusterRuntimeConfig"
        },
        "activeClusterResources":{
            "$ref":"#/definitions/ActiveClusterResources"
        },
        "driverConfig":{
            "$ref":"#/definitions/DriverConfig"
        },
        "workerConfig":{
            "$ref":"#/definitions/WorkerConfig"
        },
        "attachedNotebooks":{
            "type":"array",
            "description":"List of notebooks attached to a specific cluster.",
            "items":{
                "type":"string"
            }
        },
        "attachedSessions":{
            "type":"array",
            "description":"List of sessions attached to a specific cluster.",
            "items":{
                "$ref":"#/definitions/AttachedSession"
            }
        },
        "attachedAgentFlowCount":{
            "type":"integer",
            "default":null,
            "description":"Count of agent flow attached to a specific cluster."
        }
    }
}

Nested Schema : ActiveClusterResources

Type: object

Active resources of a cluster.

Show Source

• activeCores: number(double)
  Count of active cores.
• activeExecutorCount: number(double)
  Count of active executors.
• activeGpuCores: number(double)
  Count of active GPU cores.
• activeGpuMemoryInGBs: number(double)
  Active GPU memory in GB.
• activeMemoryInGBs: number(double)
  Active memory in GB.

{
    "description":"Active resources of a cluster.",
    "type":"object",
    "properties":{
        "activeExecutorCount":{
            "description":"Count of active executors.",
            "type":"number",
            "format":"double"
        },
        "activeCores":{
            "description":"Count of active cores.",
            "type":"number",
            "format":"double"
        },
        "activeGpuCores":{
            "description":"Count of active GPU cores.",
            "type":"number",
            "format":"double"
        },
        "activeMemoryInGBs":{
            "description":"Active memory in GB.",
            "type":"number",
            "format":"double"
        },
        "activeGpuMemoryInGBs":{
            "description":"Active GPU memory in GB.",
            "type":"number",
            "format":"double"
        }
    }
}

Nested Schema : attachedNotebooks

Type: array

List of notebooks attached to a specific cluster.

Show Source

• Array of: string

{
    "type":"array",
    "description":"List of notebooks attached to a specific cluster.",
    "items":{
        "type":"string"
    }
}

Nested Schema : attachedSessions

Type: array

List of sessions attached to a specific cluster.

Show Source

• Array of: object AttachedSession
  Details of attached sessions to a cluster

{
    "type":"array",
    "description":"List of sessions attached to a specific cluster.",
    "items":{
        "$ref":"#/definitions/AttachedSession"
    }
}

Nested Schema : ClusterRuntimeConfig

Type: object

Discriminator: type

Cluster runtime configurations.

Show Source

• initScripts: array initScripts
  Init script paths that are run in the order of definition.
• type: string
  Default Value: SPARK

  Allowed Values: [ "SPARK" ]

  Runtime type.

{
    "description":"Cluster runtime configurations.",
    "type":"object",
    "discriminator":"type",
    "properties":{
        "type":{
            "type":"string",
            "description":"Runtime type.",
            "default":"SPARK",
            "enum":[
                "SPARK"
            ]
        },
        "initScripts":{
            "type":"array",
            "description":"Init script paths that are run in the order of definition.",
            "items":{
                "$ref":"#/definitions/InitScriptPath"
            }
        }
    }
}

Nested Schema : DriverConfig

Type: object

Driver configuration.

Show Source

• driverNodeType: string
  Minimum Length: 1

  Maximum Length: 255

  Node type of optional driver node that encodes the driver node shape and associated resources.
• driverShape: string
  Minimum Length: 1

  Maximum Length: 255

  Shape of compute cluster driver instance. Example - VM.Standard2.x, VM.Standard.E3.Flex
• driverShapeConfig: object ShapeConfig
  Shape of the driver or executor if a flexible shape is used.

{
    "description":"Driver configuration.",
    "type":"object",
    "properties":{
        "driverNodeType":{
            "description":"Node type of optional driver node that encodes the driver node shape and associated resources.",
            "type":"string",
            "minLength":1,
            "maxLength":255
        },
        "driverShape":{
            "description":"Shape of compute cluster driver instance. Example - VM.Standard2.x, VM.Standard.E3.Flex",
            "type":"string",
            "minLength":1,
            "maxLength":255
        },
        "driverShapeConfig":{
            "$ref":"#/definitions/ShapeConfig"
        }
    }
}

Nested Schema : WorkerConfig

Type: object

Worker configuration.

Show Source

• maxWorkerCount: integer
  Maximum number of workers. When this property is specified, the cluster is auto-scaled.
• minWorkerCount: integer
  Minimum number of workers.
• workerShape: string
  Minimum Length: 1

  Maximum Length: 255

  Shape of the compute cluster executor instance.
• workerShapeConfig: object ShapeConfig
  Shape of the driver or executor if a flexible shape is used.

{
    "description":"Worker configuration.",
    "type":"object",
    "properties":{
        "workerShape":{
            "description":"Shape of the compute cluster executor instance.",
            "type":"string",
            "minLength":1,
            "maxLength":255
        },
        "workerShapeConfig":{
            "$ref":"#/definitions/ShapeConfig"
        },
        "minWorkerCount":{
            "description":"Minimum number of workers.",
            "type":"integer"
        },
        "maxWorkerCount":{
            "description":"Maximum number of workers. When this property is specified, the cluster is auto-scaled.",
            "type":"integer"
        }
    }
}

Nested Schema : AttachedSession

Type: object

Details of attached sessions to a cluster

Show Source

• lastCommandRun: string
  The time of the last command of file was run in this cluster.
• path: string
  The path of the attached file.
• state: string
  Allowed Values: [ "ACTIVE", "IDLE" ]

  The state of the attached file.
• type: string
  Allowed Values: [ "NOTEBOOK", "FILE" ]

  The type of the attached session.

{
    "type":"object",
    "description":"Details of attached sessions to a cluster",
    "properties":{
        "type":{
            "type":"string",
            "description":"The type of the attached session.",
            "enum":[
                "NOTEBOOK",
                "FILE"
            ]
        },
        "path":{
            "type":"string",
            "description":"The path of the attached file."
        },
        "state":{
            "type":"string",
            "description":"The state of the attached file.",
            "enum":[
                "ACTIVE",
                "IDLE"
            ]
        },
        "lastCommandRun":{
            "type":"string",
            "description":"The time of the last command of file was run in this cluster.\n"
        }
    }
}

Nested Schema : initScripts

Type: array

Init script paths that are run in the order of definition.

Show Source

• Array of: object InitScriptPath
  The path details of init script.

{
    "type":"array",
    "description":"Init script paths that are run in the order of definition.",
    "items":{
        "$ref":"#/definitions/InitScriptPath"
    }
}

Nested Schema : InitScriptPath

Type: object

The path details of init script.

Show Source

• destination(required): string
  Full path of the init script file. Example - /Workspace/Shared/Folder1/my-init.sh or /Volumes/catalogName/schemaName/volumeName/Shared/Folder1/my-init.sh.

{
    "description":"The path details of init script.",
    "type":"object",
    "required":[
        "destination"
    ],
    "properties":{
        "destination":{
            "type":"string",
            "description":"Full path of the init script file. Example - /Workspace/Shared/Folder1/my-init.sh or /Volumes/catalogName/schemaName/volumeName/Shared/Folder1/my-init.sh."
        }
    }
}

Nested Schema : ShapeConfig

Type: object

Shape of the driver or executor if a flexible shape is used.

Show Source

• gpus: integer
  Minimum Value: 0

  Total number of GPUs used for the driver or workers.
• memoryInGBs: integer
  Minimum Value: 16

  Amount of memory used for the driver or workers.
• ocpus: integer
  Minimum Value: 1

  Total number of OCPUs used for the driver or workers.

{
    "description":"Shape of the driver or executor if a flexible shape is used.",
    "properties":{
        "ocpus":{
            "description":"Total number of OCPUs used for the driver or workers.",
            "type":"integer",
            "minimum":1
        },
        "gpus":{
            "description":"Total number of GPUs used for the driver or workers.",
            "type":"integer",
            "minimum":0
        },
        "memoryInGBs":{
            "description":"Amount of memory used for the driver or workers.",
            "type":"integer",
            "minimum":16
        }
    }
}

400 Response

Bad Request (invalid query parameters, malformed headers, and so on).

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

401 Response

Unauthorized (missing or expired credentials, and so on).

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

404 Response

Not Found. The requested resource was not found.

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

429 Response

Too Many Requests. Too many requests sent to the server in a short period.

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

500 Response

Internal Server Error. The server encountered an unexpected condition preventing fulfilment of the request.

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

Default Response

Unknown Error. Error is not recognized by the system.

Headers

• opc-request-id: string
  Unique Oracle-assigned ID for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

Error information.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing.
• message(required): string
  A human-readable error message.

{
    "description":"Error information.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "description":"A short error code that defines the error, meant for programmatic parsing.",
            "type":"string"
        },
        "message":{
            "description":"A human-readable error message.",
            "type":"string"
        }
    }
}

Back to Top