Get details of a task

/tasks/{task_id}

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

NameDescription
X-SBG-Auth-Token
required
Your authentication token.

Path parameters

NameDescription
task_id
required
The ID of the task you are querying

Query parameters

NameData typeDescription
fieldsstringSelector 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:

KeyDatatype of valueDescription
"batch"booleanSet to True if the task is a parent batch task; otherwise False.
"parent"stringThe ID of the parent task, in the case that the task is part of a batch (i.e. a child task).
"batch_group"dictionaryPresent 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"dictionaryFor 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"stringThe total price for the whole task including all child tasks.
"errors"arrayIf 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:

NumberValidation error typeValidation messageComment
1error/task_validation/input/schemaValue 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.
2error/task_validation/input/invalid_name_filesSome 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.
3error/task_validation/input/files_missingSome 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.
4error/task_validation/input/secondary_files_missingSome secondary (index) files required by this input cannot be found in the projectThis 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.