Computation API

Prerequisites

• Token with capsule scope

• The computation ID to pass to the API call

The computation ID can only be accessed from the response from the API calls. A typical use cases are to use List capsule computations API to locate the computation ID from a capsule or Run capsule API to start a new computation. Both of the methods will have the computations ID in the response body that can use in computations API for further tracking and getting the results.

Get computation API

GET https://{domain}codeocean.com/api/v1/computations/{computations_id}

Path Parameters

Name	Type	Description
{domain}*	String	Your VPC domain
{computations_id}*	String	Computation's id

Headers

Name	Type	Description
Content-Type*	String	application/json
-u*	String	\ '${API Token from Code Ocean}:\' \

200: OK

{
  "id": string - the computation internal id,
  "created": float64 - computation creation time,
  "name": string - the display name of the computation,
  "run_time": int - the total run time in seconds,

  "parameters": [
    {
      "name": string parameter name,
      "value": string parameter value
    },
    {
      "name": string parameter name,
      "value": string parameter value
    }
  ],
  "result_size": float64 - result size,
  "state": string - initializing,running,finalizing, completed
}

Example of getting computation API:

Request Example

curl --location --request GET 'https://acmecorp.codeocean.com/api/v1/computations/{computations_id}' \
--header 'Content-Type: application/json' \
-u \'${CUSTOM_KEY}:\'

use this example, please change the domain to your VPC instead of acmecorp, ${CUSTOM_KEY} to your API token, and use your computation's id.

Response Example

{
    "created":1646687806,
    "end_status":"succeeded",
    "has_results":true,
    "id":"66095e3a-0747-4ec5-b8b1-95b89a428536",
    "name":"Run 6687806",
    "run_time":5,
    "state":"completed"
}

List computation result files API

POST https://{domain}codeocean.com/api/v1/computations/{computations_id}/results

Path Parameters

Name	Type	Description
{domain}*	String	Your VPC domain
{computations_id}*	String	Computation's id

Headers

Name	Type	Description
Content-Type*	String	application/json
-u*	String	\ '${API Token from Code Ocean}:\' \

Request Body

Name	Type	Description
path*	String	string - the path of the folder. The empty path will retrieve the result root folder.

200: OK

{
  "items": - array
    [
      {
        "name": string - the name of the entry,
        "path": string - full path to the item,
        "size": int64 - the item size in bytes (only available for files),
        "type": file, folder - the type of the item
      }
    ]
}

Example of listing computation result files API:

Request Example

curl --location --request POST 'https://acmecorp.codeocean.com/api/v1/computations/{computations_id}/results' \
--header 'Content-Type: application/json' \
-u \'${CUSTOM_KEY}:\' \
--data-raw '{ 
    "path": ""
}'

use this example, please change the domain to your VPC instead of acmecorp, ${CUSTOM_KEY} to your API token, and use your computation's id.

Response Example

{
  "items":
    [
      {
        "name":"fig1.png",
        "path":"fig1.png",
        "size":34003,
        "type":"file"
      },
      {
        "name":"output",
        "path":"output",
        "size":20,
        "type":"file"
      }
    ]
}

Get result file download URL API

GET https://{domain}codeocean.com/api/v1/computations/{computations_id}/results/download_url?path={PATH_TO_FILE}

Path Parameters

Name	Type	Description
{domain}*	String	Your VPC domain
{computations_id}*	String	Computation's id
{PATH_TO_FILE}*	String	path of the file under /results

Headers

Name	Type	Description
Content-Type*	String	application/json
-u*	String	\ '${API Token from Code Ocean}:\' \

200: OK

{}

You can use List computation result files API to find the path of the file.

Example of listing computation result files API:

Request Example

curl --location --request GET 'https://acmecorp.codeocean.com/api/v1/computations/66095e3a-0747-4ec5-b8b1-95b89a428536/results/download_url?path=fig1.png' \
--header 'Content-Type: application/json' \
-u \'${CUSTOM_KEY}:\'

use this example, please change the domain to your VPC instead of acmecorp, ${CUSTOM_KEY} to your API token, and use your computation's id and the file path.

Response Example

{
    "url":
        "https://s3.amazonaws.com/acmecorp-s3resultsbucket-jlfcqiv031u3/9b17d7b7-8b48-461a-95c6-ddb1a00a4e49/1d8288da-0785-4e4f-aa37-2d1db3636bc4/66095e3a-0747-4ec5-b8b1-95b89a428536/fig1.png?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=ASIASEPVU66XOZU3BPAN%2F20220317%2Fus-east-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20220317T144814Z\u0026X-Amz-Expires=3600\u0026X-Amz-Security-Token=IQoJb3JpZ2luX2VjECkaCXVzLWVhc3QtMSJGMEQCIHZsKuwxNa%2B2bFGw8MPV%2B5Th%2Fc6za2DHh6ACEJifi8LHAiBS2%2FVM%2BVvXaXuUyUwJvTOyd7srTkKROVVqqBJfn6rN9iqDBAii%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAIaDDE0NzA4MDkzNTM0MiIMps2d2Ng4fkwjFQIdKtcDr1vnJNmkc1ta81uAyxSHBQs5INsbkolyhLADVDAKPNDn7ngUl9c2ThQlIAVeFJPVvvtMVh7mBiT%2BLWCShvDW8oQRzpftMg3tyToYmm82%2BjGxe1aYTBT7f1tlfQuEibZDQ1OQK1xA9mVy47hRBKye7%2FMkCLETsOyMTEhdZR%2F%2BK1X4lgu1Su1zWgf7%2FhU%2BSFXrOPpEw%2BjCvri8sSwukY213x9GHvR%2Fj3r8Ry%2B9wbYoFetcg6tiMRnG%2F%2Fb012sjy5u2SM4TXhOmOvQHK6%2FJNJDaYGFPvXxcRoy0mzYQm3r03Axp4Mt8OilbKHzl0EQxL4d5V2y0M9SD%2F0k4oGiHpf7eMnmaBJC7Nl0GXLQT6TsYaz9fMVA84cY1A1n0kEx%2F10udyFKlpTtJ%2F2AcBRPwqs%2FpVjcZET5l65gya1NxfSspon9HRwvSz6%2FkrF1t1B5AVwo7BO%2Bv5ph1AOUjiAM7IX9SK5LUR73kAzefFRs9%2FBlrh%2BVVwkCPO7nsiP9YaE1drL%2F3wWPwuVkzhR9JmDJx1V4FCcBMevfopiYN99y9Vh0pNk1mMQwwgG6W%2BoseZ3AtmB%2B2ijy54S0MEeTlc12Iu27uBtnrkLTZPYAcUB%2FqgIqkbO90BJx2hhPCMMLky5EGOqYBcTqZWa1XR6Efbb2%2FLy5kyB72nur%2FWyLMSGLGxCjsB4LBvpV68mcQGuEqdEE2RfOhGTKYbvHPCACdGXTXnDz8a0qo%2BscIVFCsVF%2BAnHs3CYSVkNR1C3HYeJ5AV7Ii7RVwlwINNOzuBXqvIRQ8Mqr4iSQoZUweMoe4EsIoakIM15m3DsrtPt9wmECuz55DiQmDcNYvJiN7gT8CxGA63YPIKrrAeJWigA%3D%3D\u0026X-Amz-SignedHeaders=host\u0026response-content-disposition=attachment%3B%20filename%3Dfig1.png\u0026X-Amz-Signature=efaa8272ec180d7c08f83a589cb34310d82a8b98e382a47a2250d88345c46e1c"
}