Job Executions

ThreatConnect can integrate with many third-party applications and services via TC Exchange™ Apps. Once installed, an App leverages a corresponding Job to perform the actions that the App supports. As the Job runs, detailed logs of the execution will be collected, including the queued date, start date, completed date, server information, exit message, and status.

Endpoint: /api/v3/job/executions

Endpoint Options

Available Fields

Send the following request to retrieve a list of available fields that may be included in responses returned from the /v3/job/executions endpoint, which is a read-only endpoint:

OPTIONS /v3/job/executions?show=readonly

Filter Results

When retrieving data, you can use the tql query parameter to filter results with ThreatConnect Query Language (TQL).

Send the following request to retrieve a list of valid TQL parameters you can use when including the tql query parameter in a request to the /v3/job/executions endpoint:

OPTIONS /v3/job/executions/tql

Hint

See the “Retrieve Job Executions Completed During a Specific Time Range” and “Retrieve Executions for a Specific Job” sections for example use cases of the tql query parameter.

Schemas

Response Body

The default response returned from a successful GET request to the /v3/job/executions endpoint includes one or more objects with the following fields:

id: <Integer> The Job execution’s ID number.
jobId: <Integer> The ID number of the Job that was executed.
completedTime: <DateTime> The date and time when the Job execution completed. If the Job execution failed, the API response will include a failedTime field that provides the date and time when the execution failed instead of the completedTime field.
exitMessage: <String> The Job execution’s exit message.
queueTime: <DateTime> The date and time when the Job execution was queued.
serverName: <String> The name of the server on which the Job was executed.
startTime: <DateTime> The date and time when the Job execution started.
status: <String> The Job execution’s status.

Example

{
    "id": <int>,
    "jobId": <int>,
    "completedTime": "<datetime>",
    "exitMessage": "<string>",
    "queueTime": "<datetime>",
    "serverName": "<string>",
    "startTime": "<datetime>",
    "status": "<string>"
}

Retrieve Job Executions

Retrieve All Job Executions

Send the following request to retrieve data for all Job executions in your Organization:

Request

GET /v3/job/executions

Response

{
    "data": [
        {
            "id": 95,
            "jobId": 174,
            "completedTime": "2024-04-04T21:39:42Z",
            "exitMessage": "Successfully Added Attribute(s).\n",
            "queueTime": "2024-04-04T21:39:41Z",
            "serverName": "tc-job",
            "startTime": "2024-04-04T21:39:41Z",
            "status": "Completed"
        },
        {
            "id": 94,
            "jobId": 100,
            "exitMessage": "Failed for status (404)\n",
            "failedTime": "2024-05-02T17:36:40Z",
            "queueTime": "2024-05-02T17:36:38Z",
            "serverName": "tc-job",
            "startTime": "2024-05-02T17:36:38Z",
            "status": "Failed"
        },
        {...}
    ],
    "countFailure": 3,
    "status": "Success",
    "countSuccess": 92
}

Note

The countFailure and countSuccess fields provide the total number of failed and successful Job executions, respectively, included in the API response.

Retrieve Job Executions Completed During a Specific Time Range

The following request demonstrates how to use TQL to filter Job executions based on when they were completed. In this example, the API request will retrieve data only for Job executions completed within the last hour:

Request (Decoded URL)

GET /v3/job/executions?tql=completedTime > "NOW() - 1 HOUR"

Request (Encoded URL)

GET /v3/job/executions?tql=completedTime%20%3E%20%22NOW()%20-%201%20HOUR%22

Retrieve Executions for a Specific Job

The following request demonstrates how to use TQL to filter Job executions by the corresponding Job’s ID number. For instructions on obtaining a Job’s ID number, see Jobs Overview.

In this example, the API request will retrieve data only for executions of the Job whose ID number is 12345:

Request (Decoded URL)

GET /v3/job/executions?tql=jobId = 12345

Request (Encoded URL)

GET /v3/job/executions?tql=jobId%20%3D%2012345