---
title: "Run a historical job"
method: POST
path: "/api/v2/siem-historical-detections/jobs"
tags: ["Security Monitoring"]
---

# Run a historical job

`POST /api/v2/siem-historical-detections/jobs`

Run a historical job.

## Request body

- RunHistoricalJobRequest — Run a historical job request.
  - `data` RunHistoricalJobRequestData — Data for running a historical job request.
    - `attributes` RunHistoricalJobRequestAttributes — Run a historical job request.
      - `fromRule` JobDefinitionFromRule — Definition of a historical job based on a security monitoring rule.
        - `caseIndex` integer — Zero-based index of the rule case to use as the job's signal condition. When omitted, all cases are evaluated. Up to 10 cases are supported, so valid values are 0 to 9.
        - `from` integer, required — Starting time of data analyzed by the job.
        - `id` string, required — ID of the detection rule used to create the job.
        - `index` string, required — Index used to load the data.
        - `notifications` string[] — Notifications sent when the job is completed.
        - `to` integer, required — Ending time of data analyzed by the job.
      - `jobDefinition` JobDefinition — Definition of a historical job.
        - `calculatedFields` CalculatedField[] — Calculated fields.
          - `expression` string, required — Expression.
          - `name` string, required — Field name.
        - `cases` SecurityMonitoringRuleCaseCreate[], required — Cases used for generating job results. Up to 10 cases are allowed.
          - `actions` SecurityMonitoringRuleCaseAction[] — Action to perform for each rule case.
            - `options` SecurityMonitoringRuleCaseActionOptions — Options for the rule action
              - …
            - `type` 'block_ip' | 'block_user' | 'user_behavior' | 'flag_ip' — The action type.
          - `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` 'info' | 'low' | 'medium' | 'high' | 'critical', required — Severity of the Security Signal.
        - `from` integer, required — 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` string, required — Index used to load the data.
        - `message` string, required — Message for generated results.
        - `name` string, required — Job name.
        - `options` HistoricalJobOptions — Job options.
          - `anomalyDetectionOptions` SecurityMonitoringRuleAnomalyDetectionOptions — Options on anomaly detection method.
            - `bucketDuration` 300 | 600 | 900 | 1800 | 3600 | 10800 — Duration in seconds of the time buckets used to aggregate events matched by the rule. Must be greater than or equal to 300.
            - `detectionTolerance` 1 | 2 | 3 | 4 | 5 — An optional parameter that sets how permissive anomaly detection is. Higher values require higher deviations before triggering a signal.
            - `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` 1 | 6 | 12 | 24 | 48 | 168 | 336 — Learning duration in hours. Anomaly detection waits for at least this amount of historical data before it starts evaluating.
            - `learningPeriodBaseline` integer — An optional override baseline to apply while the rule is in the learning period. Must be greater than or equal to 0.
          - `detectionMethod` 'threshold' | 'new_value' | 'anomaly_detection' | 'impossible_travel' | 'hardcoded' | 'third_party' | 'anomaly_threshold' | 'sequence_detection' — The detection method.
          - `evaluationWindow` 0 | 60 | 300 | 600 | 900 | 1800 | 3600 | 7200 | 10800 | 21600 | 43200 | 86400 — 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.
          - `impossibleTravelOptions` SecurityMonitoringRuleImpossibleTravelOptions — 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` integer, nullable — 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` 0 | 60 | 300 | 600 | 900 | 1800 | 3600 | 7200 | 10800 | 21600 | 43200 | 86400 — 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.
          - `maxSignalDuration` 0 | 60 | 300 | 600 | 900 | 1800 | 3600 | 7200 | 10800 | 21600 | 43200 | 86400 — 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.
          - `newValueOptions` SecurityMonitoringRuleNewValueOptions — Options on new value detection method.
            - `forgetAfter` integer — 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` integer — 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` 'duration' | 'threshold' — The learning method used to determine when signals should be generated for values that weren't learned.
            - `learningThreshold` 0 | 1 — A number of occurrences after which signals will be generated for values that weren't learned.
          - `sequenceDetectionOptions` SecurityMonitoringRuleSequenceDetectionOptions — Options on sequence detection method.
            - `stepTransitions` SecurityMonitoringRuleSequenceDetectionStepTransition[] — Transitions defining the allowed order of steps and their evaluation windows.
              - …
            - `steps` SecurityMonitoringRuleSequenceDetectionStep[] — Steps that define the conditions to be matched in sequence.
              - …
          - `thirdPartyRuleOptions` SecurityMonitoringRuleThirdPartyOptions — Options on third party detection method.
            - `defaultNotifications` string[] — Notification targets for the logs that do not correspond to any of the cases.
            - `defaultStatus` 'info' | 'low' | 'medium' | 'high' | 'critical' — Severity of the Security Signal.
            - `rootQueries` SecurityMonitoringThirdPartyRootQuery[] — 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.
              - …
            - `signalTitleTemplate` string — A template for the signal title; if omitted, the title is generated based on the case name.
        - `queries` HistoricalJobQuery[], required — 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` 'count' | 'cardinality' | 'sum' | 'max' | 'new_value' | 'geo_data' | 'event_count' | 'none' — The aggregation type.
          - `correlatedByFields` string[] — Fields used to correlate results across queries in sequence detection rules.
          - `correlatedQueryIndex` integer — 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` 'logs' | 'audit' | 'app_sec_spans' | 'spans' | 'security_runtime' | 'network' | 'events' | 'security_signals' — Source of events, either logs, audit trail, security signals, or Datadog events. `app_sec_spans` is deprecated in favor of `spans`.
          - `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` SecurityMonitoringReferenceTable[] — 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` SecurityMonitoringThirdPartyRuleCaseCreate[] — 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` 'info' | 'low' | 'medium' | 'high' | 'critical', required — Severity of the Security Signal.
        - `to` integer, required — Ending time of data analyzed by the job.
        - `type` string — Job type.
      - `signalOutput` boolean — Whether the job outputs signals when results are converted.
    - `type` 'historicalDetectionsJobCreate' — Type of data.

## Response `201`

Status created

- JobCreateResponse — Run a historical job response.
  - `data` JobCreateResponseData — The definition of `JobCreateResponseData` object.
    - `id` string — ID of the created job.
    - `type` 'historicalDetectionsJob' — Type of payload.

## Other responses

- `400` — Bad Request
- `401` — Concurrent Modification
- `403` — Not Authorized
- `404` — Not Found
- `429` — Too many requests

---

[API](https://skmtc.net/datadog/apis/api-v2.md) · [All operations](https://skmtc.net/datadog/apis/api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/datadog/api-v2/revisions/da68bf029e4c/schema)