Get details of a task

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://api.sb.biodatacatalyst.nhlbi.nih.gov/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: api.sb.biodatacatalyst.nhlbi.nih.gov
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74

curl  -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X GET "https://api.sb.biodatacatalyst.nhlbi.nih.gov/v2/tasks/bd5e95d9-12b3-789c-45b6-34d8696571a9"

Header Fields

Name	Description
`X-SBG-Auth-Token` required	Your 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 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).

Regular task response body

The example below contains an example response body from a regular (non-batch) task.

{
  "href": "https://api.sb.biodatacatalyst.nhlbi.nih.gov/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": true,
  "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": 19,
        "system_limit": false,
        "account_limit": false,
        "instance_init": false,
        "steps_total": 19,
        "message": "Completed",
        "duration": 0,
        "queued_duration": 0,
        "running_duration": 0,
        "execution_duration": 0
      },
  "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"
    }
  }
}

Batch task response body

The example below contains an example response body from batch task.

{
    "href": "https://api.sb.biodatacatalyst.nhlbi.nih.gov/v2/tasks/67f68072-45b6-12b3-789c-37be8b0f2f04",
    "id": "67f68072-45b6-12b3-789c-37be8b0f2f04",
    "name": "Tengfei and Damir playing",
    "status": "ABORTED",
    "project": "rfranklin/batch-test",
    "use_interruptible_instances": true,
    "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": {
        "duration": '123456789',
        "running_duration": '120453636',
        "queued_duration": '3456789',
        "message": "Batch tasks list initialization.",
        "queued": 0,
        "running": 0,
        "completed": 0,
        "failed": 0,
        "aborted": 0,
        "execution_duration": 0
        "system_limit": false,
        "account_limit": false,
    },
    "price": {
        "currency": "USD",
        "amount": "0.00",
    },
    "inputs": {
        "Known_SNPs": [
            {
                "class": "File",
                "path": "567890abc8a5639cc6722063",
                "name": "dbsnp_137.b37.vcf"
            }
        ],
        <snip>
    }
}

Interpreting the response body

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": {} }` 2. 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.
`"price"`	string	The total price for the whole task including all child tasks.
`"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.