Language

English Français 日本語 한국어 Español

Datadog Site

Site help
US1 US3 US5 EU AP1 AP2 US1-FED US2-FED

List historical jobs

copy Copy pageCopied

Note: This endpoint is in beta and may be subject to changes. Please check the documentation regularly for updates.

GET https://api.ap1.datadoghq.com/api/v2/siem-historical-detections/jobshttps://api.ap2.datadoghq.com/api/v2/siem-historical-detections/jobshttps://api.datadoghq.eu/api/v2/siem-historical-detections/jobshttps://api.ddog-gov.com/api/v2/siem-historical-detections/jobshttps://api.us2.ddog-gov.com/api/v2/siem-historical-detections/jobshttps://api.datadoghq.com/api/v2/siem-historical-detections/jobshttps://api.us3.datadoghq.com/api/v2/siem-historical-detections/jobshttps://api.us5.datadoghq.com/api/v2/siem-historical-detections/jobs

Overview

List historical jobs.

Arguments

Query Strings

Name

Type

Description

page[size]

integer

Size for a given page. The maximum allowed value is 100.

page[number]

integer

Specific page number to return.

sort

string

The order of the jobs in results.

filter[query]

string

Query used to filter items from the fetched list.

Response

OK

List of historical jobs.

Expand All

Field

Type

Description

data

[object]

Array containing the list of historical jobs.

attributes

object

Historical job attributes.

createdAt

string

Time when the job was created.

createdByHandle

string

The handle of the user who created the job.

createdByName

string

The name of the user who created the job.

createdFromRuleId

string

ID of the rule used to create the job (if it is created from a rule).

jobDefinition

object

Definition of a historical job.

calculatedFields

[object]

Calculated fields.

expression [required]

string

Expression.

name [required]

string

Field name.

cases [required]

[object]

Cases used for generating job results. Up to 10 cases are allowed.

actions

[object]

Action to perform for each rule case.

options

object

Options for the rule action

duration

int64

Duration of the action in seconds. 0 indicates no expiration.

flaggedIPType

enum

Used with the case action of type 'flag_ip'. The value specified in this field is applied as a flag to the IP addresses. Allowed enum values: SUSPICIOUS,FLAGGED

userBehaviorName

string

Used with the case action of type 'user_behavior'. The value specified in this field is applied as a risk tag to all users affected by the rule.

type

enum

The action type. Allowed enum values: block_ip,block_user,user_behavior,flag_ip

condition

string

A case contains logical operations (>,>=, &&, ||) to determine if a signal should be generated based on the event counts in the previously defined queries.

name

string

Name of the case.

notifications

[string]

Notification targets.

status [required]

enum

Severity of the Security Signal. Allowed enum values: info,low,medium,high,critical

from [required]

int64

Starting time of data analyzed by the job.

groupSignalsBy

[string]

Additional grouping to perform on top of the existing groups in the query section. Must be a subset of the existing groups.

index [required]

string

Index used to load the data.

message [required]

string

Message for generated results.

name [required]

string

Job name.

options

object

Job options.

anomalyDetectionOptions

object

Options on anomaly detection method.

bucketDuration

enum

Duration in seconds of the time buckets used to aggregate events matched by the rule. Must be greater than or equal to 300. Allowed enum values: 300,600,900,1800,3600,10800

detectionTolerance

enum

An optional parameter that sets how permissive anomaly detection is. Higher values require higher deviations before triggering a signal. Allowed enum values: 1,2,3,4,5

instantaneousBaseline

boolean

When set to true, Datadog uses previous values that fall within the defined learning window to construct the baseline, enabling the system to establish an accurate baseline more rapidly rather than relying solely on gradual learning over time.

learningDuration

enum

Learning duration in hours. Anomaly detection waits for at least this amount of historical data before it starts evaluating. Allowed enum values: 1,6,12,24,48,168,336

learningPeriodBaseline

int64

An optional override baseline to apply while the rule is in the learning period. Must be greater than or equal to 0.

detectionMethod

enum

The detection method. Allowed enum values: threshold,new_value,anomaly_detection,impossible_travel,hardcoded,third_party,anomaly_threshold,sequence_detection

evaluationWindow

enum

A time window is specified to match when at least one of the cases matches true. This is a sliding window and evaluates in real time. For third party detection method, this field is not used. Allowed enum values: 0,60,300,600,900,1800,3600,7200,10800,21600

Show 2 more,43200,86400

impossibleTravelOptions

object

Options on impossible travel detection method.

baselineUserLocations

boolean

If true, signals are suppressed for the first 24 hours. In that time, Datadog learns the user's regular access locations. This can be helpful to reduce noise and infer VPN usage or credentialed API access.

baselineUserLocationsDuration

int32

The duration in days during which Datadog learns the user's regular access locations. After this period, signals are generated for accesses from unknown locations.

keepAlive

enum

Once a signal is generated, the signal will remain "open" if a case is matched at least once within this keep alive window. For third party detection method, this field is not used. Allowed enum values: 0,60,300,600,900,1800,3600,7200,10800,21600

Show 2 more,43200,86400

maxSignalDuration

enum

A signal will "close" regardless of the query being matched once the time exceeds the maximum duration. This time is calculated from the first seen timestamp. Allowed enum values: 0,60,300,600,900,1800,3600,7200,10800,21600

Show 2 more,43200,86400

newValueOptions

object

Options on new value detection method.

forgetAfter

int32

The duration in days after which a learned value is forgotten.

instantaneousBaseline

boolean

When set to true, Datadog uses previous values that fall within the defined learning window to construct the baseline, enabling the system to establish an accurate baseline more rapidly rather than relying solely on gradual learning over time.

learningDuration

int32

The duration in days during which values are learned, and after which signals will be generated for values that weren't learned. If set to 0, a signal will be generated for all new values after the first value is learned.

learningMethod

enum

The learning method used to determine when signals should be generated for values that weren't learned. Allowed enum values: duration,threshold

default: duration

learningThreshold

enum

A number of occurrences after which signals will be generated for values that weren't learned. Allowed enum values: 0,1

sequenceDetectionOptions

object

Options on sequence detection method.

stepTransitions

[object]

Transitions defining the allowed order of steps and their evaluation windows.

child

string

Name of the child step.

evaluationWindow

enum

A time window is specified to match when at least one of the cases matches true. This is a sliding window and evaluates in real time. For third party detection method, this field is not used. Allowed enum values: 0,60,300,600,900,1800,3600,7200,10800,21600

Show 2 more,43200,86400

parent

string

Name of the parent step.

steps

[object]

Steps that define the conditions to be matched in sequence.

condition

string

Condition referencing rule queries (e.g., a > 0).

evaluationWindow

enum

A time window is specified to match when at least one of the cases matches true. This is a sliding window and evaluates in real time. For third party detection method, this field is not used. Allowed enum values: 0,60,300,600,900,1800,3600,7200,10800,21600

Show 2 more,43200,86400

name

string

Unique name identifying the step.

thirdPartyRuleOptions

object

Options on third party detection method.

defaultNotifications

[string]

Notification targets for the logs that do not correspond to any of the cases.

defaultStatus

enum

Severity of the Security Signal. Allowed enum values: info,low,medium,high,critical

rootQueries

[object]

Queries to be combined with third party case queries. Each of them can have different group by fields, to aggregate differently based on the type of alert.

groupByFields

[string]

Fields to group by.

query

string

Query to run on logs.

signalTitleTemplate

string

A template for the signal title; if omitted, the title is generated based on the case name.

queries [required]

[object]

Queries for selecting logs analyzed by the job. Up to 10 queries are allowed.

additionalFilters

string

Additional filters appended to the query at evaluation time.

aggregation

enum

The aggregation type. Allowed enum values: count,cardinality,sum,max,new_value,geo_data,event_count,none

correlatedByFields

[string]

Fields used to correlate results across queries in sequence detection rules.

correlatedQueryIndex

int64

Zero-based index of the query to correlate with in sequence detection rules. Up to 10 queries are supported, so valid values are 0 to 9.

customQueryExtension

string

Custom query extension used to refine the base query.

dataSource

enum

Source of events, either logs, audit trail, security signals, or Datadog events. app_sec_spans is deprecated in favor of spans. Allowed enum values: logs,audit,app_sec_spans,spans,security_runtime,network,events,security_signals

default: logs

datasetIds

[string]

IDs of reference datasets used by this query.

distinctFields

[string]

Field for which the cardinality is measured. Sent as an array.

groupByFields

[string]

Fields to group by.

hasOptionalGroupByFields

boolean

When false, events without a group-by value are ignored by the query. When true, events with missing group-by fields are processed with N/A, replacing the missing values.

index

string

Index used to load the data for this query.

indexes

[string]

Indexes used to load the data for this query. Mutually exclusive with index.

metrics

[string]

Group of target fields to aggregate over when using the sum, max, geo data, or new value aggregations. The sum, max, and geo data aggregations only accept one value in this list, whereas the new value aggregation accepts up to five values.

name

string

Name of the query.

query

string

Query to run on logs.

queryLanguage

string

Language used to parse the query string.

referenceTables

[object]

Reference tables used in the queries.

checkPresence

boolean

Whether to include or exclude the matched values.

columnName

string

The name of the column in the reference table.

logFieldPath

string

The field in the log to match against the reference table.

ruleQueryName

string

The name of the query to apply the reference table to.

tableName

string

The name of the reference table.

tags

[string]

Tags for generated signals.

thirdPartyCases

[object]

Cases for generating results from third-party detection method. Only available for third-party detection method. Up to 10 cases are allowed.

name

string

Name of the case.

notifications

[string]

Notification targets for each case.

query

string

A query to map a third party event to this case.

status [required]

enum

Severity of the Security Signal. Allowed enum values: info,low,medium,high,critical

to [required]

int64

Ending time of data analyzed by the job.

type

string

Job type.

jobName

string

Job name.

jobStatus

string

Job status.

modifiedAt

string

Last modification time of the job.

progressRate

double

Job execution progress as a value between 0 and 1. Available for ongoing jobs.

signalOutput

boolean

Whether the job outputs signals.

id

string

ID of the job.

type

enum

Type of payload. Allowed enum values: historicalDetectionsJob

meta

object

Metadata about the list of jobs.

totalCount

int32

Number of jobs in the list.

{
  "data": [
    {
      "attributes": {
        "createdAt": "string",
        "createdByHandle": "string",
        "createdByName": "string",
        "createdFromRuleId": "string",
        "jobDefinition": {
          "calculatedFields": [
            {
              "expression": "@request_end_timestamp - @request_start_timestamp",
              "name": "response_time"
            }
          ],
          "cases": [
            {
              "actions": [
                {
                  "options": {
                    "duration": 0,
                    "flaggedIPType": "FLAGGED",
                    "userBehaviorName": "string"
                  },
                  "type": "string"
                }
              ],
              "condition": "string",
              "name": "string",
              "notifications": [],
              "status": "critical"
            }
          ],
          "from": 1729843470000,
          "groupSignalsBy": [
            "service"
          ],
          "index": "cloud_siem",
          "message": "A large number of failed login attempts.",
          "name": "Excessive number of failed attempts.",
          "options": {
            "anomalyDetectionOptions": {
              "bucketDuration": 300,
              "detectionTolerance": 5,
              "instantaneousBaseline": false,
              "learningDuration": "integer",
              "learningPeriodBaseline": "integer"
            },
            "detectionMethod": "string",
            "evaluationWindow": "integer",
            "impossibleTravelOptions": {
              "baselineUserLocations": true,
              "baselineUserLocationsDuration": "integer"
            },
            "keepAlive": "integer",
            "maxSignalDuration": "integer",
            "newValueOptions": {
              "forgetAfter": "integer",
              "instantaneousBaseline": false,
              "learningDuration": "integer",
              "learningMethod": "string",
              "learningThreshold": "integer"
            },
            "sequenceDetectionOptions": {
              "stepTransitions": [
                {
                  "child": "string",
                  "evaluationWindow": "integer",
                  "parent": "string"
                }
              ],
              "steps": [
                {
                  "condition": "string",
                  "evaluationWindow": "integer",
                  "name": "string"
                }
              ]
            },
            "thirdPartyRuleOptions": {
              "defaultNotifications": [],
              "defaultStatus": "critical",
              "rootQueries": [
                {
                  "groupByFields": [],
                  "query": "source:cloudtrail"
                }
              ],
              "signalTitleTemplate": "string"
            }
          },
          "queries": [
            {
              "additionalFilters": "string",
              "aggregation": "string",
              "correlatedByFields": [],
              "correlatedQueryIndex": "integer",
              "customQueryExtension": "string",
              "dataSource": "logs",
              "datasetIds": [],
              "distinctFields": [],
              "groupByFields": [],
              "hasOptionalGroupByFields": false,
              "index": "string",
              "indexes": [],
              "metrics": [],
              "name": "string",
              "query": "a > 3",
              "queryLanguage": "string"
            }
          ],
          "referenceTables": [
            {
              "checkPresence": false,
              "columnName": "string",
              "logFieldPath": "string",
              "ruleQueryName": "string",
              "tableName": "string"
            }
          ],
          "tags": [],
          "thirdPartyCases": [
            {
              "name": "string",
              "notifications": [],
              "query": "string",
              "status": "critical"
            }
          ],
          "to": 1729847070000,
          "type": "string"
        },
        "jobName": "string",
        "jobStatus": "string",
        "modifiedAt": "string",
        "progressRate": "number",
        "signalOutput": false
      },
      "id": "string",
      "type": "string"
    }
  ],
  "meta": {
    "totalCount": "integer"
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Authorized

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Curl command
curl -X GET "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/siem-historical-detections/jobs" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

                
"""
List historical jobs returns "OK" response
"""

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.security_monitoring_api import SecurityMonitoringApi

configuration = Configuration()
configuration.unstable_operations["list_historical_jobs"] = True
with ApiClient(configuration) as api_client:
    api_instance = SecurityMonitoringApi(api_client)
    response = api_instance.list_historical_jobs()

    print(response)

Instructions

First install the library and its dependencies and then save the example to example.py and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"
# List historical jobs returns "OK" response

require "datadog_api_client"
DatadogAPIClient.configure do |config|
  config.unstable_operations["v2.list_historical_jobs".to_sym] = true
end
api_instance = DatadogAPIClient::V2::SecurityMonitoringAPI.new
p api_instance.list_historical_jobs()

Instructions

First install the library and its dependencies and then save the example to example.rb and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" rb "example.rb"
// List historical jobs returns "OK" response

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	"github.com/DataDog/datadog-api-client-go/v2/api/datadog"
	"github.com/DataDog/datadog-api-client-go/v2/api/datadogV2"
)

func main() {
	ctx := datadog.NewDefaultContext(context.Background())
	configuration := datadog.NewConfiguration()
	configuration.SetUnstableOperationEnabled("v2.ListHistoricalJobs", true)
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewSecurityMonitoringApi(apiClient)
	resp, r, err := api.ListHistoricalJobs(ctx, *datadogV2.NewListHistoricalJobsOptionalParameters())

	if err != nil {
		fmt.Fprintf(os.Stderr, "Error when calling `SecurityMonitoringApi.ListHistoricalJobs`: %v\n", err)
		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
	}

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `SecurityMonitoringApi.ListHistoricalJobs`:\n%s\n", responseContent)
}

Instructions

First install the library and its dependencies and then save the example to main.go and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" go run "main.go"
// List historical jobs returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.SecurityMonitoringApi;
import com.datadog.api.client.v2.model.ListHistoricalJobsResponse;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    defaultClient.setUnstableOperationEnabled("v2.listHistoricalJobs", true);
    SecurityMonitoringApi apiInstance = new SecurityMonitoringApi(defaultClient);

    try {
      ListHistoricalJobsResponse result = apiInstance.listHistoricalJobs();
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling SecurityMonitoringApi#listHistoricalJobs");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Instructions

First install the library and its dependencies and then save the example to Example.java and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" java "Example.java"
// List historical jobs returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_security_monitoring::ListHistoricalJobsOptionalParams;
use datadog_api_client::datadogV2::api_security_monitoring::SecurityMonitoringAPI;

#[tokio::main]
async fn main() {
    let mut configuration = datadog::Configuration::new();
    configuration.set_unstable_operation_enabled("v2.ListHistoricalJobs", true);
    let api = SecurityMonitoringAPI::with_config(configuration);
    let resp = api
        .list_historical_jobs(ListHistoricalJobsOptionalParams::default())
        .await;
    if let Ok(value) = resp {
        println!("{:#?}", value);
    } else {
        println!("{:#?}", resp.unwrap_err());
    }
}

Instructions

First install the library and its dependencies and then save the example to src/main.rs and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run
/**
 * List historical jobs returns "OK" response
 */

import { client, v2 } from "@datadog/datadog-api-client";

const configuration = client.createConfiguration();
configuration.unstableOperations["v2.listHistoricalJobs"] = true;
const apiInstance = new v2.SecurityMonitoringApi(configuration);

apiInstance
  .listHistoricalJobs()
  .then((data: v2.ListHistoricalJobsResponse) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data)
    );
  })
  .catch((error: any) => console.error(error));

Instructions

First install the library and its dependencies and then save the example to example.ts and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" tsc "example.ts"