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:

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.

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 booleanIndicates 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 stringParameter 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 Download URL

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

This API allows for the generation of a URL to download a result file from a Computation.

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/download_url?path=GSM12345_R1_fastqc.html \
   -u "cop_d23dasd312":

Request Example Python SDK

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

Response

url stringDownload 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)

PreviousCapsule NextData Asset

Was this helpful?