Jump to

• Request
• Response

(Preview) List experiment runs

post

/20260430/aiDataPlatforms/{aiDataPlatformId}/workspaces/{workspaceKey}/mlops/api/2.0/mlflow/runs/search

(Preview) Returns a list of experiment runs in a 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

Header Parameters

• dh-user-principal: string
  The DH User Principal Header .
• 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.

Body ()

Details of experiment runs to fetch.

Root Schema : ListExperimentRunsDetails

Type: object

Details of experiment runs to fetch.

Show Source

• experiment_ids: array experiment_ids
  List of experiment IDs to search over.
• filter: string
  A filter expression over params, metrics, and tags, that allows returning a subset of runs. The syntax is a subset of SQL that supports ANDing together binary operations between a param, metric, or tag and a constant. Example: metrics.rmse < 1 and params.model_class = 'LogisticRegression' You can select columns with special characters (hyphen, space, period, etc.) by using double quotes: metrics."model class" = 'LinearRegression' and tags."user-name" = 'Tomas' Supported operators are =, !=, >, >=, <, and <="." div>
• max_results: integer(int32)
  Maximum number of runs desired. If unspecified, defaults to 1000. All servers are guaranteed to support a max_results threshold of at least 50,000 but may support more. Callers are encouraged to pass max_results explicitly and leverage page_token to iterate.
• order_by: array order_by
  List of columns to be ordered by, including attributes, params, metrics, and tags with an optional "DESC" or "ASC" annotation, where "ASC" is the default. Example: ["params.input DESC", "metrics.alpha ASC", "metrics.rmse"] Tiebreaks are done by start_time DESC followed by run_id for runs with the same start time (and this is the default ordering criterion if order_by is not provided).
• page_token: string
  Token indicating the page of experiment runs to fetch.
• run_view_type: string
  Allowed Values: [ "ACTIVE_ONLY", "DELETED_ONLY", "ALL" ]

  Qualifier for type of runs to be returned. If unspecified, returns only active runs.

{
    "description":"Details of experiment runs to fetch.",
    "type":"object",
    "properties":{
        "experiment_ids":{
            "type":"array",
            "items":{
                "type":"string"
            },
            "description":"List of experiment IDs to search over."
        },
        "max_results":{
            "type":"integer",
            "format":"int32",
            "description":"Maximum number of runs desired. If unspecified, defaults to 1000. All servers are guaranteed to \nsupport a max_results threshold of at least 50,000 but may support more. Callers are encouraged to \npass max_results explicitly and leverage page_token to iterate.\n"
        },
        "page_token":{
            "type":"string",
            "description":"Token indicating the page of experiment runs to fetch."
        },
        "filter":{
            "type":"string",
            "description":"A filter expression over params, metrics, and tags, that allows returning a subset of runs. The syntax is \na subset of SQL that supports ANDing together binary operations between a param, metric, or tag and a constant.\nExample: metrics.rmse < 1 and params.model_class = 'LogisticRegression'\nYou can select columns with special characters (hyphen, space, period, etc.) by using \ndouble quotes: metrics.\"model class\" = 'LinearRegression' and tags.\"user-name\" = 'Tomas'\nSupported operators are =, !=, >, >=, <, and <=.\n"
        },
        "order_by":{
            "type":"array",
            "items":{
                "type":"string"
            },
            "description":"List of columns to be ordered by, including attributes, params, metrics, and tags with an \noptional \"DESC\" or \"ASC\" annotation, where \"ASC\" is the default. \nExample: [\"params.input DESC\", \"metrics.alpha ASC\", \"metrics.rmse\"] \nTiebreaks are done by start_time DESC followed by run_id for runs with the same start time (and this is \nthe default ordering criterion if order_by is not provided).\n"
        },
        "run_view_type":{
            "description":"Qualifier for type of runs to be returned. If unspecified, returns only active runs.",
            "type":"string",
            "enum":[
                "ACTIVE_ONLY",
                "DELETED_ONLY",
                "ALL"
            ]
        }
    }
}

Nested Schema : experiment_ids

Type: array

List of experiment IDs to search over.

Show Source

• Array of: string

{
    "type":"array",
    "items":{
        "type":"string"
    },
    "description":"List of experiment IDs to search over."
}

Nested Schema : order_by

Type: array

List of columns to be ordered by, including attributes, params, metrics, and tags with an optional "DESC" or "ASC" annotation, where "ASC" is the default. Example: ["params.input DESC", "metrics.alpha ASC", "metrics.rmse"] Tiebreaks are done by start_time DESC followed by run_id for runs with the same start time (and this is the default ordering criterion if order_by is not provided).

Show Source

• Array of: string

{
    "type":"array",
    "items":{
        "type":"string"
    },
    "description":"List of columns to be ordered by, including attributes, params, metrics, and tags with an \noptional \"DESC\" or \"ASC\" annotation, where \"ASC\" is the default. \nExample: [\"params.input DESC\", \"metrics.alpha ASC\", \"metrics.rmse\"] \nTiebreaks are done by start_time DESC followed by run_id for runs with the same start time (and this is \nthe default ordering criterion if order_by is not provided).\n"
}

Back to Top

Response

Supported Media Types

• application/json

200 Response

Successful operation. List of experiment runs is retrieved.

Headers

• opc-next-page: string
  For pagination of a list of items. When paging through a list, if this header appears in the response, then a partial list might have been returned. Include this value as the `page` parameter for the subsequent GET request to get the next batch of items.
• 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 : ExperimentRunCollection

Type: object

Result of listing experiment runs.

Show Source

• next_page_token: string
  Token that can be used to retrieve the next page of runs. An empty token means that no more runs are available for retrieval.
• runs(required): array runs
  Runs that match the search criteria.

{
    "type":"object",
    "description":"Result of listing experiment runs.",
    "required":[
        "runs"
    ],
    "properties":{
        "runs":{
            "description":"Runs that match the search criteria.",
            "type":"array",
            "items":{
                "$ref":"#/definitions/ExperimentRun"
            }
        },
        "next_page_token":{
            "description":"Token that can be used to retrieve the next page of runs. An empty token means that no more runs are available for retrieval.",
            "type":"string"
        }
    }
}

Nested Schema : runs

Type: array

Runs that match the search criteria.

Show Source

• Array of: object ExperimentRun
  Details of an experiment run.

{
    "description":"Runs that match the search criteria.",
    "type":"array",
    "items":{
        "$ref":"#/definitions/ExperimentRun"
    }
}

Nested Schema : ExperimentRun

Type: object

Details of an experiment run.

Show Source

• data: object ExperimentRunData
  Run data.
• info: object ExperimentRunInfo
  Run metadata.
• inputs: object ExperimentRunInputs
  Run inputs.
• outputs: object ExperimentRunOutputs
  Run outputs.

{
    "description":"Details of an experiment run.",
    "type":"object",
    "properties":{
        "info":{
            "$ref":"#/definitions/ExperimentRunInfo"
        },
        "data":{
            "$ref":"#/definitions/ExperimentRunData"
        },
        "inputs":{
            "$ref":"#/definitions/ExperimentRunInputs"
        },
        "outputs":{
            "$ref":"#/definitions/ExperimentRunOutputs"
        }
    }
}

Nested Schema : ExperimentRunData

Type: object

Run data.

Show Source

• metrics: array metrics
  Metrics logged for the run.
• params: array params
  Parameters logged for the run.
• tags: array tags
  Tags to log.

{
    "description":"Run data.",
    "type":"object",
    "properties":{
        "metrics":{
            "type":"array",
            "description":"Metrics logged for the run.",
            "items":{
                "$ref":"#/definitions/ExperimentRunMetric"
            }
        },
        "params":{
            "type":"array",
            "description":"Parameters logged for the run.",
            "items":{
                "$ref":"#/definitions/ExperimentRunParam"
            }
        },
        "tags":{
            "type":"array",
            "description":"Tags to log.",
            "items":{
                "$ref":"#/definitions/ExperimentRunTag"
            }
        }
    }
}

Nested Schema : ExperimentRunInfo

Type: object

Run metadata.

Show Source

• artifact_uri: string
  Artifact URI of the run.
• end_time: integer(int64)
  Unix timestamp in milliseconds when the run ended.
• experiment_id: string
  ID of the associated experiment.
• lifecycle_stage: string
  Lifecycle stage of the experiment, e.g., 'active' or 'deleted'.
• run_id: string
  Unique identifier for the run.
• run_name: string
  Name of the run.
• run_uuid: string
  UUID of the run.
• start_time: integer(int64)
  Unix timestamp in milliseconds when the run started.
• status: string
  Allowed Values: [ "RUNNING", "SCHEDULED", "FINISHED", "FAILED", "KILLED", "INTERNAL_ERROR" ]

  Status of the run.
• user_id: string
  User ID that created the run.

{
    "description":"Run metadata.",
    "type":"object",
    "properties":{
        "run_id":{
            "type":"string",
            "description":"Unique identifier for the run."
        },
        "run_name":{
            "type":"string",
            "description":"Name of the run."
        },
        "experiment_id":{
            "type":"string",
            "description":"ID of the associated experiment."
        },
        "status":{
            "description":"Status of the run.",
            "type":"string",
            "x-obmcs-top-level-enum":"#/definitions/ExperimentRunStatus",
            "enum":[
                "RUNNING",
                "SCHEDULED",
                "FINISHED",
                "FAILED",
                "KILLED",
                "INTERNAL_ERROR"
            ]
        },
        "start_time":{
            "type":"integer",
            "format":"int64",
            "description":"Unix timestamp in milliseconds when the run started."
        },
        "end_time":{
            "type":"integer",
            "format":"int64",
            "description":"Unix timestamp in milliseconds when the run ended."
        },
        "artifact_uri":{
            "type":"string",
            "description":"Artifact URI of the run."
        },
        "lifecycle_stage":{
            "type":"string",
            "description":"Lifecycle stage of the experiment, e.g., 'active' or 'deleted'."
        },
        "run_uuid":{
            "type":"string",
            "description":"UUID of the run."
        },
        "user_id":{
            "type":"string",
            "description":"User ID that created the run."
        }
    }
}

Nested Schema : ExperimentRunInputs

Type: object

Run inputs.

Show Source

• dataset_inputs: array dataset_inputs
  Dataset inputs for the run.
• model_inputs: array model_inputs
  Model inputs for the run.

{
    "description":"Run inputs.",
    "type":"object",
    "properties":{
        "dataset_inputs":{
            "type":"array",
            "description":"Dataset inputs for the run.",
            "items":{
                "$ref":"#/definitions/DatasetInput"
            }
        },
        "model_inputs":{
            "type":"array",
            "description":"Model inputs for the run.",
            "items":{
                "$ref":"#/definitions/ModelInput"
            }
        }
    }
}

Nested Schema : ExperimentRunOutputs

Type: object

Run outputs.

Show Source

• model_outputs: array model_outputs
  Model outputs for the run.

{
    "description":"Run outputs.",
    "type":"object",
    "properties":{
        "model_outputs":{
            "type":"array",
            "description":"Model outputs for the run.",
            "items":{
                "$ref":"#/definitions/ModelOutput"
            }
        }
    }
}

Nested Schema : metrics

Type: array

Metrics logged for the run.

Show Source

• Array of: object ExperimentRunMetric
  Run metric.

{
    "type":"array",
    "description":"Metrics logged for the run.",
    "items":{
        "$ref":"#/definitions/ExperimentRunMetric"
    }
}

Nested Schema : params

Type: array

Parameters logged for the run.

Show Source

• Array of: object ExperimentRunParam
  Run param.

{
    "type":"array",
    "description":"Parameters logged for the run.",
    "items":{
        "$ref":"#/definitions/ExperimentRunParam"
    }
}

Nested Schema : tags

Type: array

Tags to log.

Show Source

• Array of: object ExperimentRunTag
  Run tag.

{
    "type":"array",
    "description":"Tags to log.",
    "items":{
        "$ref":"#/definitions/ExperimentRunTag"
    }
}

Nested Schema : ExperimentRunMetric

Type: object

Run metric.

Show Source

• key: string
  Name of the metric.
• step: integer(int64)
  Step at which to log the metric.
• timestamp: integer(int64)
  Unix timestamp in milliseconds when this metric was recorded.
• value: number(double)
  Value of the metric.

{
    "type":"object",
    "description":"Run metric.",
    "properties":{
        "key":{
            "description":"Name of the metric.",
            "type":"string"
        },
        "value":{
            "description":"Value of the metric.",
            "type":"number",
            "format":"double"
        },
        "timestamp":{
            "type":"integer",
            "format":"int64",
            "description":"Unix timestamp in milliseconds when this metric was recorded."
        },
        "step":{
            "type":"integer",
            "format":"int64",
            "description":"Step at which to log the metric."
        }
    }
}

Nested Schema : ExperimentRunParam

Type: object

Run param.

Show Source

• key: string
  Key of the parameter.
• value: string
  Value of the parameter.

{
    "type":"object",
    "description":"Run param.",
    "properties":{
        "key":{
            "description":"Key of the parameter.",
            "type":"string"
        },
        "value":{
            "description":"Value of the parameter.",
            "type":"string"
        }
    }
}

Nested Schema : ExperimentRunTag

Type: object

Run tag.

Show Source

• key: string
  Key of the run tag.
• value: string
  Value of the run tag.

{
    "type":"object",
    "description":"Run tag.",
    "properties":{
        "key":{
            "description":"Key of the run tag.",
            "type":"string"
        },
        "value":{
            "description":"Value of the run tag.",
            "type":"string"
        }
    }
}

Nested Schema : dataset_inputs

Type: array

Dataset inputs for the run.

Show Source

• Array of: object DatasetInput
  DatasetInput

{
    "type":"array",
    "description":"Dataset inputs for the run.",
    "items":{
        "$ref":"#/definitions/DatasetInput"
    }
}

Nested Schema : model_inputs

Type: array

Model inputs for the run.

Show Source

• Array of: object ModelInput
  Model input.

{
    "type":"array",
    "description":"Model inputs for the run.",
    "items":{
        "$ref":"#/definitions/ModelInput"
    }
}

Nested Schema : DatasetInput

Type: object

DatasetInput

Show Source

• dataset(required): object Dataset
  Dataset. Represents a reference to data used for training, testing, or evaluation during the model development process.
• tags: array tags
  Tags for the dataset input.

{
    "description":"DatasetInput",
    "type":"object",
    "required":[
        "dataset"
    ],
    "properties":{
        "dataset":{
            "$ref":"#/definitions/Dataset"
        },
        "tags":{
            "type":"array",
            "description":"Tags for the dataset input.",
            "items":{
                "$ref":"#/definitions/InputTag"
            }
        }
    }
}

Nested Schema : Dataset

Type: object

Dataset. Represents a reference to data used for training, testing, or evaluation during the model development process.

Show Source

• digest(required): string
  Digest (hash) of the dataset.
• name(required): string
  Name of the dataset.
• profile: string
  Profile of the dataset.
• schema: string
  Schema of the dataset.
• source(required): string
  URI or path to the dataset source.
• source_type(required): string
  Type of the dataset source.

{
    "type":"object",
    "description":"Dataset. Represents a reference to data used for training, testing, or evaluation during the model development process.",
    "required":[
        "name",
        "digest",
        "source_type",
        "source"
    ],
    "properties":{
        "name":{
            "description":"Name of the dataset.",
            "type":"string"
        },
        "digest":{
            "description":"Digest (hash) of the dataset.",
            "type":"string"
        },
        "source_type":{
            "description":"Type of the dataset source.",
            "type":"string"
        },
        "source":{
            "description":"URI or path to the dataset source.",
            "type":"string"
        },
        "schema":{
            "description":"Schema of the dataset.",
            "type":"string"
        },
        "profile":{
            "description":"Profile of the dataset.",
            "type":"string"
        }
    }
}

Nested Schema : tags

Type: array

Tags for the dataset input.

Show Source

• Array of: object InputTag
  Run tag.

{
    "type":"array",
    "description":"Tags for the dataset input.",
    "items":{
        "$ref":"#/definitions/InputTag"
    }
}

Nested Schema : InputTag

Type: object

Run tag.

Show Source

• key(required): string
  Key of the tag.
• value(required): string
  Value of the tag.

{
    "type":"object",
    "description":"Run tag.",
    "required":[
        "key",
        "value"
    ],
    "properties":{
        "key":{
            "description":"Key of the tag.",
            "type":"string"
        },
        "value":{
            "description":"Value of the tag.",
            "type":"string"
        }
    }
}

Nested Schema : ModelInput

Type: object

Model input.

Show Source

• model_id(required): string
  ID of the model input.

{
    "type":"object",
    "description":"Model input.",
    "required":[
        "model_id"
    ],
    "properties":{
        "model_id":{
            "description":"ID of the model input.",
            "type":"string"
        }
    }
}

Nested Schema : model_outputs

Type: array

Model outputs for the run.

Show Source

• Array of: object ModelOutput
  Model output.

{
    "type":"array",
    "description":"Model outputs for the run.",
    "items":{
        "$ref":"#/definitions/ModelOutput"
    }
}

Nested Schema : ModelOutput

Type: object

Model output.

Show Source

• model_id(required): string
  ID of the model input.
• step: integer(int64)
  Step at which the model was produced.

{
    "type":"object",
    "description":"Model output.",
    "required":[
        "model_id"
    ],
    "properties":{
        "model_id":{
            "description":"ID of the model input.",
            "type":"string"
        },
        "step":{
            "type":"integer",
            "format":"int64",
            "description":"Step at which the model was produced."
        }
    }
}

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