Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

GetFindingHistory

Returns history for a Security Hub finding in the last 90 days. The history includes changes made to any fields in the AWS Security Finding Format (ASFF).

Request Syntax


POST /findingHistory/get HTTP/1.1
Content-type: application/json

{
   "EndTime": "string",
   "FindingIdentifier": { 
      "Id": "string",
      "ProductArn": "string"
   },
   "MaxResults": number,
   "NextToken": "string",
   "StartTime": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

EndTime

An ISO 8601-formatted timestamp that indicates the end time of the requested finding history.

If you provide values for both StartTime and EndTime, Security Hub returns finding history for the specified time period. If you provide a value for StartTime but not for EndTime, Security Hub returns finding history from the StartTime to the time at which the API is called. If you provide a value for EndTime but not for StartTime, Security Hub returns finding history from the CreatedAt timestamp of the finding to the EndTime. If you provide neither StartTime nor EndTime, Security Hub returns finding history from the CreatedAt timestamp of the finding to the time at which the API is called. In all of these scenarios, the response is limited to 100 results, and the maximum time period is limited to 90 days.

This field accepts only the specified formats. Timestamps can end with Z or ("+" / "-") time-hour [":" time-minute]. The time-secfrac after seconds is limited to a maximum of 9 digits. The offset is bounded by +/-18:00. Here are valid timestamp formats with examples:

YYYY-MM-DDTHH:MM:SSZ (for example, 2019-01-31T23:00:00Z)
YYYY-MM-DDTHH:MM:SS.mmmmmmmmmZ (for example, 2019-01-31T23:00:00.123456789Z)
YYYY-MM-DDTHH:MM:SS+HH:MM (for example, 2024-01-04T15:25:10+17:59)
YYYY-MM-DDTHH:MM:SS-HHMM (for example, 2024-01-04T15:25:10-1759)
YYYY-MM-DDTHH:MM:SS.mmmmmmmmm+HH:MM (for example, 2024-01-04T15:25:10.123456789+17:59)

Type: Timestamp

Required: No

FindingIdentifier

Identifies which finding to get the finding history for.

Type: AwsSecurityFindingIdentifier object

Required: Yes

MaxResults

The maximum number of results to be returned. If you don’t provide it, Security Hub returns up to 100 results of finding history.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 100.

Required: No

NextToken

A token for pagination purposes. Provide NULL as the initial value. In subsequent requests, provide the token included in the response to get up to an additional 100 results of finding history. If you don’t provide NextToken, Security Hub returns up to 100 results of finding history for each request.

Type: String

Required: No

StartTime

A timestamp that indicates the start time of the requested finding history.

If you provide values for both StartTime and EndTime, AWS Security Hub returns finding history for the specified time period. If you provide a value for StartTime but not for EndTime, Security Hub returns finding history from the StartTime to the time at which the API is called. If you provide a value for EndTime but not for StartTime, Security Hub returns finding history from the CreatedAt timestamp of the finding to the EndTime. If you provide neither StartTime nor EndTime, Security Hub returns finding history from the CreatedAt timestamp of the finding to the time at which the API is called. In all of these scenarios, the response is limited to 100 results, and the maximum time period is limited to 90 days.

YYYY-MM-DDTHH:MM:SSZ (for example, 2019-01-31T23:00:00Z)
YYYY-MM-DDTHH:MM:SS.mmmmmmmmmZ (for example, 2019-01-31T23:00:00.123456789Z)
YYYY-MM-DDTHH:MM:SS+HH:MM (for example, 2024-01-04T15:25:10+17:59)
YYYY-MM-DDTHH:MM:SS-HHMM (for example, 2024-01-04T15:25:10-1759)
YYYY-MM-DDTHH:MM:SS.mmmmmmmmm+HH:MM (for example, 2024-01-04T15:25:10.123456789+17:59)

Type: Timestamp

Required: No

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "NextToken": "string",
   "Records": [ 
      { 
         "FindingCreated": boolean,
         "FindingIdentifier": { 
            "Id": "string",
            "ProductArn": "string"
         },
         "NextToken": "string",
         "Updates": [ 
            { 
               "NewValue": "string",
               "OldValue": "string",
               "UpdatedField": "string"
            }
         ],
         "UpdateSource": { 
            "Identity": "string",
            "Type": "string"
         },
         "UpdateTime": "string"
      }
   ]
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

NextToken

A token for pagination purposes. Provide this token in the subsequent request to GetFindingsHistory to get up to an additional 100 results of history for the same finding that you specified in your initial request.

Type: String

Records

A list of events that altered the specified finding during the specified time period.

Type: Array of FindingHistoryRecord objects

Errors

For information about the errors that are common to all actions, see Common Errors.

InternalException

Internal server error.

HTTP Status Code: 500

InvalidAccessException

The account doesn't have permission to perform this action.

HTTP Status Code: 401

InvalidInputException

The request was rejected because you supplied an invalid or out-of-range value for an input parameter.

HTTP Status Code: 400

LimitExceededException

The request was rejected because it attempted to create resources beyond the current AWS account or throttling limits. The error code describes the limit exceeded.

HTTP Status Code: 429