Get details of a task

/tasks/{task_id}

For general information on the API, including formatting, parameters, and pagination, please see the API Overview.

This call returns details of the specified task. The task is referred to by its ID, which you can obtain by making the call to list all tasks you can access.

https://cavatica-api.sbgenomics.com/v2/tasks/{task_id}

The task details include its creator, its start and end time, the number of jobs completed in it, and its input and output files. You can also see the status of the task.

Request

Example request

GET /v2/tasks/bd5e95d9-12b3-789c-45b6-34d8696571a9 HTTP/1.1
Host: cavatica-api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
curl  -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X GET "https://cavatica-api.sbgenomics.com/v2/tasks/bd5e95d9-12b3-789c-45b6-34d8696571a9"

Header Fields

Name

Description

X-SBG-Auth-Token
required

Your CAVATICA authentication token.

Path parameters

Name

Description

task_id
required

The ID of the task you are querying

Query parameters

Name

Data type

Description

fields

string

Selector specifying a subset of fields to include in the response.

Response

See a list of CAVATICA-specific response codes that may be contained in the body of the response.

The response body for a batch task will contain information about the task. The content will be a little different depending on whether the task in question is a batch task (a parent task) or one task that is part of a batch (a child task).
The following key-value pairs in the response body indicate the batch status of the task:

Key

Datatype of value

Description

"batch"

boolean

Set to True if the task is a parent batch task; otherwise False.

"parent"

string

The ID of the parent task, in the case that the task is part of a batch (i.e. a child task).

"batch_group"

dictionary

Present only for child tasks.
This describes the structure of the parent task, i.e. the criteria by which tasks are batched.

  1. If tasks are batched per item in the input, the structure is as shown in the following example:

"batch_group": { "value": "C18-146.fastq", "fields": {} }

  1. If tasks are batched by metadata fields, the structure is as shown in the following example:

"batch_group": { "value": "hg19, E18127-pool40-L2355", "fields": { "metadata.library_id": "hg19", "metadata.sample_id": "E18127-pool40-L2355" } }

"execution_status"

dictionary

For a parent task, this describes the number of child tasks in any given state, in the following form:

"execution_status": { "message": "Running", "queued": 1, "running": 5, "completed": 2, "failed": 1, "aborted": 0 }

For a child task or a single task (not part of a batch), the execution status lists a number of steps.

"errors"

array

If there are any errors related to task validation, they will be represented here in an array. Each of the errors is represented by a dictionary, containing the error type, a human readable message, and the ID of the input responsible for the input. There may also be further data, if it is available.

See below for an example of the error array, and information on interpreting it.

Example of the "errors" array, contained in the response body:

"errors": [
    {
      "type": "error/task_validation/input/schema",
      "message": "Value for this input does not match the expected type.",
      "input_id": "FASTQ"
    },
    {
      "type": "error/task_validation/input/schema",
      "message": "Value for this input does not match the expected type.",
      "input_id": "SnpEff_Database"
    },
    {
      "type": "error/task_validation/input/schema",
      "message": "Value for this input does not match the expected type.",
      "input_id": "Reference"
    }
  ]

More on task validations and validation errors

Whenever you request to create or run a task on the Platform, it will be validated against several criteria. Similarly, when you create or modify any input for a task, these will be validated.
All validations errors are stored as a high-level errors array property in the API response.

You may get the following errors if a task fails these validations:

Number

Validation error type

Validation message

Comment

1

error/task_validation/input/schema

Value for this input does not match the expected type.

This error arises when the input value for a task, or a single app in a task, is the wrong data type, for example, if you have submitted an array of files to an input port that expects a single file, or if you have submitted a file to an input port that expects a string.

2

error/task_validation/input/invalid_name_files

Some files on this input contain impermissible characters in their name. Please change the file names before running the task since irregular file names can often lead to certain tools failing.

This error occurs when you enter a space or other special character that can cause problems when running a command line tool.

3

error/task_validation/input/files_missing

Some files found in this input cannot be found in the project.

All of the input files need to be in the same project where the task is being run. This error occurs when some input files cannot be found in the project.

4

error/task_validation/input/secondary_files_missing

Some secondary (index) files required by this input cannot be found in the project

This error occurs when an app requires secondary files for an input, typically index files (i.e. a .BAI file for a .BAM file input) and those files cannot be found in the project.

Example response body for a non-batch task (i.e. one initiated with the batch query parameter set to false.

{
  "href": "https://cavatica-api.sbgenomics.com/v2/tasks/bd5e95d9-12b3-789c-45b6-34d8696571a9",
  "id": "bd5e95d9-12b3-789c-45b6-34d8696571a9",
  "name": "grep run - 11-26-15 14:14:14",
  "status": "COMPLETED",
  "project": "RFranklin/test",
  "use_interruptible_instances": false,
  "execution_settings": {
    "instance_type": "c4.2xlarge;ebs-gp2;2000",
    "max_parallel_instances": 1
  },
  "app": "RFranklin/my-project/grep/5",
  "type": "v2",
  "batch": false,
  "created_by": "RFranklin",
  "executed_by": "RFranklin",
  "start_time": "2015-11-26T14:14:14Z",
  "end_time": "2015-11-26T14:20:30Z",
  "execution_status": {
    "steps_completed": 1,
    "steps_total": 1,
    "message": "Running"
  },
  "price": {
    "currency": "USD",
    "amount": "0.23",
    "breakdown": {
      "storage": "0.00",
      "computation": "0.23"
    }
  },
  "inputs": {
    "file_to_search": {
      "class": "File",
      "path": "567890abc9b0307bc0414164",
      "name": "test-text.txt"
    },
    "lines_of_context": 2,
    "pattern_to_find": "word"
  },
  "outputs": {
    "pattern_found": {
      "path": "567890abc1e5339df0414123",
      "name": "output.txt",
      "class": "File"
    }
  }
}

Example response body for a batch task (i.e. a parent task).

{
    "href": "https://cavatica-api.sbgenomics.com/v2/tasks/48f79ccf-12b3-45b6-789c-b1e8d88dabcd",
    "id": "48f79ccf-12b3-45b6-789c-b1e8d88dabcd",
    "name": "Sample task",
    "status": "ABORTED",
    "project": "rfranklin/batch-test",
    "app": "rfranklin/batch-test/whole-exome-sequencing-gatk-2-3-9-lite/2",
    "type": "v2",
    "created_by": "rfranklin",
    "executed_by": "rfranklin",
    "start_time": "2016-04-05T12:18:14Z",
    "end_time": "2016-04-07T11:04:42Z",
    "batch": true,
    "batch_input": "FASTQ",
    "batch_by": {
        "type": "CRITERIA",
        "criteria": [
            "metadata.sample_id",
            "metadata.library_id"
        ]
    },
    "execution_status": {
        "message": "Aborted",
        "queued": 0,
        "running": 0,
        "completed": 0,
        "failed": 0,
        "aborted": 0
    },
    "price": {
        "currency": "USD",
        "amount": "0.00"
    },
    "inputs": {
        "Known_SNPs": [
            {
                "class": "File",
                "path": "567890abc8a5136ec6127063",
                "name": "dbsnp_137.b37.vcf"
            }
        ],
        "Known_Indels": [
            {
                "class": "File",
                "path": "567890abc0b27cfe6e8c13b7",
                "name": "1000G_phase1.indels.b37.vcf"
            },
            {
                "class": "File",
                "path": "567890abc0b27cfe6e8c13c2",
                "name": "Mills_and_1000G_gold_standard.indels.b37.sites.vcf"
            }
        ],
        "Target_BED": {
            "class": "File",
            "path": "567890abc8a5136ec6127063",
            "name": "exome_targets.b37.bed"
        },
        "SnpEff_Database": {
            "class": "File",
            "path": "567890abc0b27cfe6e8c13c8",
            "name": "snpEff_v3_6_GRCh37.75.zip"
        },
        "Reference": {
            "class": "File",
            "path": "567890abc0b27cfe6e8c13b8",
            "name": "human_g1k_v37_decoy.fasta"
        },
        "FASTQ": [
            {
                "class": "File",
                "path": "567890abc8a5136ec6127063",
                "name": "C18-146.fastq"
            },
            {
                "class": "File",
                "path": "567890abc0b27cfe6e8c13d0",
                "name": "C18-99.fastq"
            },
            {
                "class": "File",
                "path": "567890abc0b27cfe6e8c13c9",
                "name": "C24-141.fastq"
            },
            {
                "class": "File",
                "path": "567890abcb27cfe6e8c13c1",
                "name": "C27-190.fastq"
            },
            {
                "class": "File",
                "path": "567890abc0b27cfe6e8c13bb",
                "name": "C28-139.fastq"
            },
            {
                "class": "File",
                "path": "567890abc0b27cfe6e8c13ca",
                "name": "C29-97.fastq"
            },
            {
                "class": "File",
                "path": "567890abc0b27cfe6e8c13bd",
                "name": "C30-101.fastq"
            },
            {
                "class": "File",
                "path": "567890abc0b27cfe6e8c13cf",
                "name": "C30-126.fastq"
            }
        ]
    }
}

Language
Click Try It! to start a request and see the response here!