Computation

Prerequisites

• Generated Access Token with Capsule Scope

• The Computation ID

The Computation ID can only be accessed from the Computation Object.

A typical use case is to use:

• List Capsule Computations

• Run Computation

Both methods will have the Computation ID in the Response that can be used in Computations API for further tracking and getting results.

When running a Pipeline, the Data Asset mount point will be the mount point of the Data Asset currently attached to the Pipeline. If the Pipeline does not have a mount point accessible (from a Data Asset) and the user attempts to run the Pipeline with a replaced Data Asset in the API, they will encounter an error due to an incorrect file path.

When replacing Data Assets, it is only possible to replace External Data Assets with other External Assets and Internal Data Assets with other Internal Assets.

Computation Object

• id string

  Computational id

• created float64

  Computation create time

• name string

  Display name of the Computation

• run_time integer

  Total run time in seconds

• cloud_workstation boolean Indicates whether this Computation is a cloud workstation

• state enum

  • initializing, running, finalizing, completed

• end_status enum

  • stopped, failed, succeeded

• exit_code integer

  Value will be 0 when the code runs successfully and non-zero when it doesn't. Any error in a Pipeline will have an exit code value of 1. Only exists once state (above) is completed.

• has_results boolean

  Indicates whether the Computation has results

• parameters array (Optional)

  Run parameters

  • name string

    Parameter name

    • value string Parameter value

• data_assets array<dictionary> (Optional)

  Attached Data Assets

  • id string

    Attached Data Asset ID

  • mount string

    Attached Data Asset mount

• nextflow_profile string (Optional) Pipeline Nextflow profile

• processes array<dictionary> (Optional) Pipeline processes information

  • name string Pipeline process name (as it appears in the main.nf)

  • capsule_id string ID of the Capsule executed in the process

  • version boolean Capsule version in case it's Released

  • public boolean Indicates the Capsule is a Code Ocean App

  • parameters array<dictionary> Run Parameters

    • name string Parameter Label

    • param_name string Parameter Name

    • value string Parameter Value

Get Computation

GET https://{codeocean-domain}/api/v1/computations/{computation_id}

This API allows for the retrieval of information from a Computational run.

Path Parameters

Name	Type
computation_id*	string

Scope

Type	Permission
Capsule	Read

Request Example Bash

curl https://{codeocean-domain}/api/v1/computations/c229ed13-ec06-43d0-abd9-4d481af3f5e3 \
   -u "cop_d23dasd312":

Request Example Python SDK

computation = client.computations.get_computation(computation_id="8f174aed-64ce-43eb-9c16-64d25da84bda")

Response

Computation Object

List Computation Result Files

POST https://{codeocean-domain}/api/v1/computations/{computation_id}/results

This API allows for listing of result files generated by a Computation.

Path Parameters

Name	Type
computation_id*	string

Request Body

Name	Type	Description
path	string	The path of the folder. Empty path will retrieve the /results root folder.

Scope

Type	Permission
Capsule	Read

Request Example Bash

curl -H "Content-Type: application/json" -u ${CUSTOM_KEY}: -X POST https://${co_domain}/api/v1/computations/${computation_id}/results --data-raw '{"path": "subfolder"}'

Request Example Python SDK

result_paths = client.computations.list_computation_results(
    computation_id=computation_id,
    path="subfolder",
)

Response

{
    "items":[
        {
            "name":"result.txt",
            "path":"subfolder/result.txt",
            "size":0,
            "type":"file"
        }
    ]
}

Get Result File URLs

GET https://{codeocean-domain}/api/v1/computations/{computation_id}/results/urls?path={path_to_file}

This API allows for the generation of two URLs to a Computation result file:

• download_url - signed URL for downloading the file

• view_url - signed URL for viewing the file in the browser

This API was introduced in Code Ocean version 4.0. The previous Get Result File Download URL API is deprecated but will be supported until August 2026.

Path Parameters

Name	Type
computation_id*	string
path_to_file*	string

Scope

Type	Permission
Capsule	Read

Request Example Bash

curl https://{domain}/api/v1/computations/9390055d-7884-4997-8dfc-88bf7445b617/results/urls?path=GSM12345_R1_fastqc.html \
   -u "cop_d23dasd312":

Request Example Python SDK

urls = client.computations.get_result_file_urls(
    computation_id="8f174aed-64ce-43eb-9c16-64d25da84bda",
    path="GSM12345_R1_fastqc.html",
)

Response

• download_url string Download file URL

• view_url string View file URL

Delete Computation

DELETE https://{domain}/api/v1/computations/{computation_id}

This API allows for the deletion of a Computational run. If it is running, the Computation will stop.

Path Parameters

Name	Type
computation_id*	string

Scope

Type	Permission
Capsule	Read/Write

Request Example Bash

curl -X DELETE https://${co_domain}/api/v1/computations/${computation_id} \
   -u ${ACCESS_TOKEN}:

Request Example Python SDK

client.computations.delete_computation(computation_id="8f174aed-64ce-43eb-9c16-64d25da84bda")

Rename Computation

PATCH https://{domain}/api/v1/computations/{computation_id}?name={computation_name}

This API allows for the renaming of an existing Computational run immediately after it has been initiated.

Request Body

Name	Type
computation_id*	string
computation_name	string

Scope

Type	Permission
Capsule	Read/Write

Request Example Bash

curl --location --request PATCH https://${co_domain}/api/v1/computations/${computation_id}?name=${computation_name} \
--header 'Content-Type: application/json' \
-u ${ACCESS_TOKEN}: 

Request Example Python SDK

client.computations.rename_computation(
    computation_id=computation_id,
    name=new_name
)

Run Capsule

POST https://{domain}/api/v1/computations

This API allows for the running of Capsules/Pipelines with Data Assets and Ordered or Named Parameters.

Prerequisite

Before using this API call, you may need AWS Cloud Credentials configured as Secrets or an Assumable Role, if you are using Data Assets from Cloud Resources.

Request Body

Name	Type
capsule_id*	string
pipeline_id	string
nextflow_profile	string
data_assets*	array<dict>
id*	string
mount	string
parameters	array<string>
named_parameters	array<dict>
processes	array<dict>

Scope

Type	Permission
Capsule	Read/Write
Data Asset	Read

Request Example Bash

curl -X POST https://{domain}/api/v1/computations \
   -u "cop_d23dasd312": \
   -H "Content-Type: application/json" \
   --data-raw '{
     "capsule_id": "4bc97533-6eb4-48ac-966f-648548a756d2"
   }'

Request Example Python SDK

from codeocean.computation import RunParams

run_params = RunParams(capsule_id="4bc97533-6eb4-48ac-966f-648548a756d2")

computation = client.computations.run_capsule(run_params)

Response

Computation Object

Run Capsule with Data Assets and Ordered Parameters

Request Example Bash

curl -X POST "https://codeocean.[my-domain].com/api/v1/computations" \
   --header "Content-Type: application/json" \
   -u "cop_d23dasd312": \
   --data-raw '{
      "capsule_id":"eb082456-d031-4a42-80b0-f209b8728927",
      "data_assets" : [
        {
            "id": "eeefcc52-b445-4e3c-80c5-0e65526cd712",
            "mount": "Reference"
        }
    ],
       "parameters": [
         "75","1","HS25","SingleEnded","","","1","","","","","","","False","False"
       ]  
}'

Request Example Python SDK

from codeocean.computation import RunParams, DataAssetsRunParam

data_assets=[
        DataAssetsRunParam(id="1az0c240-1a9z-192b-pa4c-22bac5ffa17b",
                              mount="Reference")
        ]    

run_params = RunParams(capsule_id="4bc97533-6eb4-48ac-966f-648548a756d2",
                       data_assets=data_assets,
                       parameters=[
                              "75","1","HS25","SingleEnded"
                              ]    
                )

computation = client.computations.run_capsule(run_params)

Run Capsule with Data Assets and Named Parameters

Request Example Bash

curl -X POST "https://codeocean.[my-domain].com/api/v1/computations" \
   --header "Content-Type: application/json" \
   -u "cop_d23dasd312": \
   --data-raw '{
       "capsule_id":"4c4cd610-83bf-4a9b-9dfb-3faf6c29d11b",
       "data_assets" : [
        {
            "id": "9c5cf74f-196b-4ed1-868c-8cf95c1f7182",
            "mount": "Reference"
        }
    ],
       "named_parameters": [
		{
			"param_name": "NumberOfThreads",
			"value": "1"
		},
    {
			"param_name":"NumberOfFiles",
			"value": "10"
		} 
	]
}'

Request Example Python SDK

from codeocean import CodeOcean
from codeocean.computation import RunParams, DataAssetsRunParam, NamedRunParam

data_assets=[
        DataAssetsRunParam(id="1az0c240-1a9z-192b-pa4c-22bac5ffa17b",
                              mount="Reference")
        ]    
      
named_parameters=[
              NamedRunParam(param_name="NumThreads",value="2")
                       ]

run_params = RunParams(
              capsule_id="4bc97533-6eb4-48ac-966f-648548a756d2",
              data_assets=data_assets,
              named_parameter=named_parameters    
               )

computation = client.computations.run_capsule(run_params)

Run Pipeline

Request Example Bash

curl -X POST "https://codeocean.[my-domain].com/api/v1/computations" \
   --header "Content-Type: application/json" \
   -u "cop_d23dasd312": \
   --data-raw '{
     "pipeline_id": "4bc97533-6eb4-48ac-966f-648548a756d2"
    }'

Request Example Python SDK

from codeocean.computation import RunParams, PipelineProcessParams

run_params = RunParams(
                pipeline_id="4bc97533-6eb4-48ac-966f-648548a756d2"
                )

computation = client.computations.run_capsule(run_params)

Run Pipeline with Data Assets and Ordered Capsules

Request Example Bash

curl -X POST "https://codeocean.[my-domain].com/api/v1/computations" \
   --header "Content-Type: application/json" \
   -u "cop_d23dasd312": \
   --data-raw '{
       "pipeline_id":"e7a77780-b8ae-439e-89ac-fac2549da91b",
       "data_assets" : [
        {
            "id": "eeefcc52-b445-4e3c-80c5-0e65526cd712",
            "mount": "Reference"
        }
    ],
	"processes": [
		{
			"name": "capsule_art_simulation_illumina_1",
			"parameters": [
				"75","1","HS25","SingleEnded","","","1","","","","","","","False","False"
			]		
		},
		{
			"name": "capsule_copy_of_fast_qc_2",
			"parameters": [
				""
			]		
		}
	]
}'

Request Example Python SDK

from codeocean.computation import RunParams, DataAssetsRunParam, PipelineProcessParams

data_assets=[
        DataAssetsRunParam(id="1az0c240-1a9z-192b-pa4c-22bac5ffa17b",
                              mount="Reference")
        ]    
    
processes=[
          PipelineProcessParams(
                    name="capsule_star_alignment_1",
                    parameters=[
                        "1","_R1_fastq.gz","R2_fastq.gz"
                        ]
                  )
        ]
        
run_params = RunParams(
                    capsule_id="4bc97533-6eb4-48ac-966f-648548a756d2",
                    data_assets=data_assets,
                    processes=processes    
               )

computation = client.computations.run_capsule(run_params)

Run Pipeline with Data Asset and Named Capsules

Request Example Bash

curl -X POST "https://codeocean.[my-domain].com/api/v1/computations" \
   --header "Content-Type: application/json" \
   -u "cop_d23dasd312": \
   --data-raw '{
       "pipeline_id":"4c4cd610-83bf-4a9b-9dfb-3faf6c29d11b",
       "data_assets" : [
        {
            "id": "eeefcc52-b445-4e3c-80c5-0e65526cd712",
            "mount": "Reference"
        }
    ],
	"processes": [
		{
			"name": "capsule_np_create_files_test_3",
			"named_parameters": [
				{
					"param_name": "NumFiles",
					"value": "1"
				} 
			]
		},
		{
			"name": "capsule_np_add_number_test_gh_4",
			"named_parameters": [
				{
					"param_name": "AddNumber",
					"value": "1"
				} 
			]
		}
	]
}'

Request Example Python SDK

from codeocean.computation import (
                   RunParams, 
                   DataAssetsRunParam, 
                   PipelineProcessParams,
                   NamedRunParam
                 )

data_assets=[
        DataAssetsRunParam(id="1az0c240-1a9z-192b-pa4c-22bac5ffa17b",
                              mount="Reference")
        ]    
    
processes=[
          PipelineProcessParams(
                    name="capsule_bwa_alignment_5",
                    named_parameters=[
                          NamedRunParam(param_name="NumThreads",value="2")
                           ]
        ]
        
run_params = RunParams(
                    capsule_id="4bc97533-6eb4-48ac-966f-648548a756d2",
                    data_assets=data_assets,
                    processes=processes    
               )

computation = client.computations.run_capsule(run_params)

Run Pipeline with Data Assets and Ordered + Named Capsules

Request Example Bash

curl -X POST "https://codeocean.[my-domain].com/api/v1/computations" \
   --header "Content-Type: application/json" \
   -u "cop_d23dasd312": \
   --data-raw '{
       "pipeline_id":"cd4ef788-b404-4406-8bda-76b5e41a7b8d",
       "data_assets" : [
        {
            "id": "eeefcc52-b445-4e3c-80c5-0e65526cd712",
            "mount": "Reference"
        }
    ],
    "processes": [
		{
			"name": "capsule_art_simulation_illumina_1",
			"parameters": [
				"75","1","HS25","SingleEnded","","","1","","","","","","","False","False"
			]		
		},
		{
			"name": "capsule_np_create_files_test_3",
			"named_parameters": [
				{
					"param_name": "NumFiles",
					"value": "1"
				} 
			]
		},
	]
}'

Request Example Python SDK

from codeocean.computation import (
                   RunParams, 
                   DataAssetsRunParam, 
                   PipelineProcessParams,
                   NamedRunParam
                 )

data_assets=[
        DataAssetsRunParam(id="1az0c240-1a9z-192b-pa4c-22bac5ffa17b",
                              mount="Reference")
        ]    
    
processes=[
          PipelineProcessParams(
                    name="capsule_bwa_alignment_5",
                    named_parameters=[
                          NamedRunParam(param_name="NumThreads",value="2")
                           ],
         PipelineProcessParams(
                    name="capsule_star_alignment_1",
                    parameters=[
                        "1","_R1_fastq.gz","R2_fastq.gz"
                        ]  
        ]
        
run_params = RunParams(
                    capsule_id="4bc97533-6eb4-48ac-966f-648548a756d2",
                    data_assets=data_assets,
                    processes=processes    
               )

computation = client.computations.run_capsule(run_params)