Skip to main content
Kinetic Community

Show Run

This web method is used to retrieve runs of trees for a specific source.  It is similar to the List Runs web method, but contains the details of only a single run. The URL for this web method contains the runs action scoped to the specified Source, followed by the ID of the specific run to retrieve.  An additional include parameter may be added to the body content to specify any child data to return with the run.

Details

HTTP Request

Method: GET

URL: /app/api/v1/sources/{SOURCE}/runs/{RUN_ID}

Body Content:

{
    "include": ""
}

 

Notes:  The parts in the URL denoted by curly braces {} are called route parameters.  These are pieces of data that can be passed to the API as variables.

 

URL Route Parameters

This method requires only one route parameter, which is the name of the Source the trees are associated to.

 

Route Parameter Name Description Required / Optional
SOURCE The name of the Source to retrieve runs for. Required
RUN_ID The ID of the specific run to retrieve. Required

 

Body Content

This method also accepts extra parameters passed in the body content to limit the number or runs that are returned.  

 

Body Parameter Name Description Required / Optional
include Include specific child data with the run.  By default, only details about the run object are returned.  This parameter allows you to include visible task and task message details with the run.  This value must be a comma-separated list of specific child objects to include.  Available child objects are: tasks, tasks.messages. Optional

 

Example:

{
    "include": "tasks,tasks.messages"
}

 

HTTP Response

Response Type: application/json

Response Data:

A successful API response will contain a 200 response code and a JSON formatted response body.  The JSON response object will contain the following properties:

 

Response Property Description
run Details of the run.

 

Example Response:

{
    "run": {
        ...
    }
}

 

A failed API response will contain either a 400 or a 500 series response code based on the exception type, and a JSON formatted response body containing the exception message.  See the table below for the types of responses that may be encountered with this API web method.

 

Example of a failed request:

Response Code: 404

Response Body:

{
    "message": "Unknown source:  BAD_SOURCE"
}

 

Response Codes

Response Code Reason
200 Successful request.
400 If the format of the RUN_ID route parameter is not an integer.
401 If a Basic Authentication header was provided, but the credentials were not valid.
403 If the source has any applied API policy rules, and one or more of the policy rules was violated.
404 If the provided source, or the provided run ID was not found in Kinetic Task.
500 If there was an unexpected server error.

 

Examples

Example - Include visible tasks and task messages

This is an example showing how to retrieve the details for a run of a tree, along with all visible tasks and task messages.  This example does not use any authorization, so no headers need to be provided.

In this example, you can see the details of the run was returned, with one visible task.

 

list-tasks.png

 

Method: GET

URL: /app/api/v1/sources/Playground/runs/9

 

URL Parameters:

  1. source - Playground

 

Body Content:

{
    "include": "tasks,tasks.messages"
}

 

Response Code: 200

Response Body:

{
    "run": {
        "createdAt": "2014-07-18T14:08:47.487Z",
        "createdBy": "SYSTEM",
        "id": 9,
        "sourceData": null,
        "sourceId": null,
        "status": "Complete",
        "tasks": [
            {
                "branchId": 17,
                "createdAt": "2014-07-18T14:08:50.700Z",
                "createdBy": "SYSTEM",
                "deferredResults": null,
                "definitionId": "utilities_defer_v1",
                "duration": 18,
                "id": 173,
                "messages": [],
                "nodeId": "utilities_defer_v1_1",
                "nodeName": "Deferred Task",
                "results": "<results>\ <result name=\"deferral_token\">c9c509a4b2e1ededb478e28dc2e0b3d7ea37f785<\/result>\ <result name=\"deferred_value\" type=\"String\" \/>\ <\/results>",
                "status": "Deferred",
                "token": "c9c509a4b2e1ededb478e28dc2e0b3d7ea37f785"
                "updatedAt": "2014-07-18T14:08:51.048Z",
                "updatedBy": "SYSTEM"
            }
        ],
        "tree": {
            "name": "My First Tree",
            "sourceGroup": "Documentation",
            "source": {
                "name": "Playground"
            }
        },
        "updatedAt": "2014-07-18T14:08:47.540Z",
        "updatedBy": "SYSTEM"
    }
}