Skip to main content
Kinetic Community

List Runs

This web method is used to retrieve runs of trees for a specific source.  It is similar to the Show Run web method, but contains a list of all runs that match the parameters. The URL for this web method contains the runs action scoped to the specified Source.  Additional parameters may be added to the body content to specify the exact run data to return.

Details

HTTP Request

Method: GET

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

Body Content:

{
    "sourceGroup": "ACME3 > iPad Request",
    "tree": "Procurement"
}

 

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

 

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
sourceGroup Identifies the group within the Source the runs are associated to. Optional
tree Identifies the name of the tree or local routine within the Source. Optional
sourceId Identifies the sourceId of the source application. 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:

{
    "sourceGroup": "ACME3 > iPad Request",
    "tree": "Procurement",
    "sourceId": "KS0000000000555",
    "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
count The number of runs that matched the qualification.
limit The number of runs returned in the response.
offset The starting point for the return data. For example, an offset of 50 specifies that the items that are returned should start with item number 51 (since the numbering is one-based) in the collection.
runs The list of runs that exist for the Source, with any additional body parameter filters.

 

Example Response:

{
    "count": 2,
    "limit": 1000,
    "offset": 0,
    "runs": [
        {...},
        {...},
        ...
    ]
}

 

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 number of routine runs associated to a base run exceeds the value of the limit parameter.
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 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 a list of runs for a tree, along with all visible tasks and task messages.  This example does not use any authorization, so no headers need to be provided.  Pagination is also not used in this example, so no limit or offset parameters are provided.

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

 

list-tasks.png

 

Method: GET

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

 

URL Parameters:

  1. source - Playground

 

Body Content:

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

 

Response Code: 200

Response Body:

{
    "count": 1,
    "limit": 1000,
    "offset": 0,
    "runs": [
        {
            "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"
        }
    ]
}