Add Comments to an Asynchronous Job

When you submit an asynchronous job, you can use the comments request property to provide a description of the job. During execution, the Python script can add comments by calling oml.output_comments(). When you retrieve the completed job result, the comments field contains the submitted description and any comments added by the script during execution.

Prerequisites

Before running the example, obtain an OAuth access token. See Obtain an OAuth Access Token. Ensure that the BREASTCANCER table is available and that the Python environment supports the AutoML functionality used in the example.

Note:

The oml.output_comments() function is available only in an OML4Py client built against Python 3.13. If the request body specifies a conda environment based on Python 3.12, the function will be unavailable and script execution will fail.

Example: Submit a Table-Apply Job and Retrieve Its Comments

This example shows how to:

  • Register the model_tuning_comments script in the script repository.
  • Submit an asynchronous table-apply job with a comment.
  • Check the job status.
  • Retrieve the completed job result and its comments.

Register the Table-Apply Script

The model_tuning_comments script uses AutoML to tune a neural network classification model. It adds a comment before model tuning begins and another after tuning completes to identify the best model.

Run the following PL/SQL block in a SQL session connected to the database to register model_tuning_comments in the script repository: 

begin
-- table-apply
sys.pyqScriptCreate('model_tuning_comments',
'def test_mt(input):
    import oml
    from oml import automl
    df = oml.push(input)
    import sklearn as skl
    oml.output_comments("Before Model Tuning.")
    at = automl.ModelTuning(mining_function = "classification",
                            parallel=4)
    train, test = df.split(ratio=(0.9, 0.1), seed = 1234)
    X, y = train[:,0:-1], train[:,-1]
    X_test, y_test = test[:,0:-1], test[:,-1]
    results = at.tune("nn", X, y)
    tuned_model = results["best_model"]
    oml.output_comments("Model Tuning completed, best model: " +
                        tuned_model._algorithm_name)
    y_pred = tuned_model.predict(X_test)["PREDICTION"].pull()
    score = skl.metrics.accuracy_score(y_test.pull(), y_pred)
    return "Test score on best model: {}".format(score)
', FALSE, TRUE);
end;
/

The arguments specify the following:

  • The first argument specifies the name under which the script is stored in the repository.
  • The second argument contains the Python function definition as a string.
  • The third argument, V_GLOBAL, controls whether the script is globally accessible. Setting it to FALSEmakes the script private to its owner.
  • The fourth argument, V_OVERWRITE, controls whether an existing script with the same name is replaced. Setting it to TRUE replaces the existing script.
Submit the Job

The following request submits an asynchronous table-apply job and uses the comments property to provide a description of the job: 

curl -i -k -X POST \
    --header "Authorization: Bearer ${token}" \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    -d '{
        "input": "BREASTCANCER",
        "parameters": "{\"oml_input_type\":\"pandas.DataFrame\"}",
        "asyncFlag": true,
        "comments": "Model tuning job."
    }' \
    "<oml-cloud-service-location-url>/oml/api/py-scripts/v2/table-apply/model_tuning_comments"

The response has HTTP status 201 Created and includes a Location header containing the job ID: 

HTTP/2 201 Created
server: nginx/1.14.1
date: Thu, 23 Jul 2026 15:46:25 GMT
content-length: 0
strict-transport-security: max-age=31536000;includeSubDomains
x-content-type-options: nosniff
set-cookie: JSESSIONID=node0a2ukgrg0zetn34usmt4qdu7p16.node0;
Path=/oml; Secure; HttpOnly
expires: Thu, 01 Jan 1970 00:00:00 GMT
location: https://<oml-cloud-service-location-url>/oml/api/py-scripts/v2/jobs/<job_id>
Check the Job Status

Use the job ID returned in the Location header to check the job status. A 202 Accepted response indicates that the job is still running. When the job completes, the response is 302 Found and includes the result URL in the Content-Location header. 

curl -i -k -X GET \
    --header "Authorization: Bearer ${token}" \
    --header 'Accept: application/json' \
    "<oml-cloud-service-location-url>/oml/api/py-scripts/v2/jobs/<job_id>"

Check the status until the job completes. When the job is complete, it returns:

HTTP/2 302 Found
server: nginx/1.14.1
date: Thu, 23 Jul 2026 15:50:43 GMT
content-length: 0
strict-transport-security: max-age=31536000;includeSubDomains
x-content-type-options: nosniff
content-location: https://<oml-cloud-service-location-url>/oml/api/py-scripts/
v2/jobs/<job_id>/result
Retrieve the Job Result

Use the result URL to retrieve the completed job result:

curl -i -k -X GET \
    --header "Authorization: Bearer ${token}" \
    --header 'Accept: application/json' \
    "<oml-cloud-service-location-url>/oml/api/py-scripts/v2/jobs/<job_id>/result"

The comments field in the response contains the comment provided when the job was submitted and the comments added by the script during execution: 

{
    "result": "Test score on best model: 0.9482758620689655",
    "comments": "Model tuning job. Before Model Tuning. Model Tuning completed, best model: Neural Network",
    "status": "FINISH"
}

In this example, Model tuning job. is the comment provided in the request. The script adds Before Model Tuning. and Model Tuning completed, best model: Neural Network during execution by calling oml.output_comments(). The completed job result includes all three comments in the comments field.

Submit Other Asynchronous Jobs with Comments

You can also use the comments request property when submitting asynchronous jobs through other Python function endpoints, such as do-eval, row-apply, group-apply, and index-apply. Follow the same procedure described in the preceding example to submit the job, check its status, and retrieve the result and comments.