2026/11/18 - AWS Abuse Signal API - 3 new api methods
Changes This release introduces the AWS Abuse Signal API, enabling customers to programmatically submit and track AWS abuse reports.
Submits a structured report. Amazon Web Services validates it and returns a report ID. A successful response confirms that Amazon Web Services received your report. It doesn't mean that Amazon Web Services has reached an outcome. Use GetAbuseReportStatus with the report ID to check the report's status and outcome.
This operation is idempotent within a time window. If you provide a clientToken, duplicate requests within 24 hours return the existing report ID. If you omit it, the service generates a token scoped to 5 minutes.
See also: AWS API Documentation
Request Syntax
client.create_abuse_report(
report={
'xarf': {...}|[...]|123|123.4|'string'|True|None
},
correlationId='string',
clientToken='string'
)
dict
[REQUIRED]
The abuse report data in XARF format. Provide the report under the xarf key.
xarf (:ref:`document<document>`) --
A JSON object that conforms to the XARF v4 specification. At a minimum, the document must include the XARF core fields, including the required category and type fields that classify the report (for example, category content with type phishing). For the XARF core fields and detailed schema definitions of each report type, see the XARF v4 Technical Specification on the XARF website.
If you suspect that activity is illegal, use the XARF description field to explain why and name the laws concerned.
Testing your integration
To test your integration, add the tag lifecycle:test to the report. Amazon Web Services validates test reports and returns a report ID and status in the same way as other reports, but doesn't process them as abuse reports. Amazon Web Services deletes test reports shortly after submission.
Use test values only, such as example.com and the IP address ranges reserved for documentation (192.0.2.0/24, 198.51.100.0/24 and 203.0.113.0/24). Don't add this tag to a real abuse report.
Tag keys that begin with aws: are reserved.
string
An optional correlation ID for tracking the report in the reporter's system. The service echoes this value back in responses, and you can use it to filter reports with ListAbuseReportStatuses.
string
An optional, client-provided idempotency token that ensures the operation completes no more than once. If the token matches a previous request within 24 hours, the service returns the existing report ID instead of creating a new report. When you omit this token, the service automatically generates one that is scoped to a 5-minute window.
dict
Response Syntax
{
'reportId': 'string',
'correlationId': 'string'
}
Response Structure
(dict) --
The response from a CreateAbuseReport request. Contains the identifier that Amazon Web Services assigned to your report, which you use to track it.
reportId (string) --
The unique identifier assigned to the submitted abuse report. Use this ID with GetAbuseReportStatus to track processing.
correlationId (string) --
The correlation ID that you provided in the request, if any. The service echoes this value back in the response.
Retrieves the current processing status of a previously submitted abuse report, including the status, submission timestamp, and last-update time.
You can poll this operation to track the report's status. PROCESSING confirms that Amazon Web Services received your report and is processing it. COMPLETED means Amazon Web Services finished resolving the report, and the response includes a reasonCode. The time to reach COMPLETED may vary and can take up to several days depending on the scope and complexity of the suspected abuse.
See also: AWS API Documentation
Request Syntax
client.get_abuse_report_status(
reportId='string'
)
string
[REQUIRED]
The unique identifier of the abuse report to retrieve status for. This is the reportId that is returned by CreateAbuseReport.
dict
Response Syntax
{
'reportId': 'string',
'correlationId': 'string',
'status': 'QUEUED'|'PROCESSING'|'COMPLETED',
'description': 'string',
'reasonCode': 'ACTIONED'|'NOT_RESOLVABLE_TO_AWS'|'REVIEWED_NO_AWS_ACTION'|'CONTENT_DOWN_OR_INACCESSIBLE'|'NEED_MORE_INFORMATION',
'submittedAt': datetime(2015, 1, 1),
'lastUpdatedAt': datetime(2015, 1, 1)
}
Response Structure
(dict) --
The response from a GetAbuseReportStatus request. Contains the report's current status, when you submitted it, and when its status last changed.
reportId (string) --
The unique identifier of the abuse report.
correlationId (string) --
The reporter-provided correlation ID for cross-referencing.
status (string) --
The current processing status of the abuse report. Valid values are QUEUED (the report has been received and queued for processing), PROCESSING (the report has been received and is being processed), and COMPLETED (downstream resolution is finished).
description (string) --
A human-readable description of the current status.
reasonCode (string) --
A code that explains the resolution outcome. This value is returned only after the report reaches the terminal COMPLETED status; it is absent while the report is QUEUED or PROCESSING. Treat an unrecognized value as opaque, because the set of reason codes is append-only.
submittedAt (datetime) --
The date and time when the abuse report was submitted.
lastUpdatedAt (datetime) --
The date and time when the status was last updated.
Lists abuse report statuses for the calling account, ordered by submission time, with optional filtering and pagination.
Use the correlationId parameter to filter results by the reporter-provided correlation ID that was specified during report submission.
Results are paginated. Use nextToken to retrieve additional results.
See also: AWS API Documentation
Request Syntax
client.list_abuse_report_statuses(
correlationId='string',
nextToken='string',
maxResults=123
)
string
Filters results by the reporter-provided correlation ID.
string
The pagination token for retrieving the next page of results. Omit this parameter to return the first page of results.
integer
The maximum number of results to return in a single page. Valid range: 1–50. The default is 50.
dict
Response Syntax
{
'reports': [
{
'reportId': 'string',
'correlationId': 'string',
'status': 'QUEUED'|'PROCESSING'|'COMPLETED',
'description': 'string',
'reasonCode': 'ACTIONED'|'NOT_RESOLVABLE_TO_AWS'|'REVIEWED_NO_AWS_ACTION'|'CONTENT_DOWN_OR_INACCESSIBLE'|'NEED_MORE_INFORMATION'
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
The response from a ListAbuseReportStatuses request. Contains one page of abuse report statuses and, when more results remain, a token for retrieving the next page.
reports (list) --
A list of abuse report status items. This list is empty when no reports are found for the calling account, or when no reports match the specified correlationId filter.
(dict) --
Status information for an individual abuse report. The ListAbuseReportStatuses operation returns this structure in its reports list.
reportId (string) --
The unique identifier of the abuse report.
correlationId (string) --
The reporter-provided correlation ID for cross-referencing.
status (string) --
The current processing status of the abuse report. Valid values are QUEUED (the report has been received and queued for processing), PROCESSING (the report has been received and is being processed), and COMPLETED (downstream resolution is finished).
description (string) --
A human-readable description of the status.
reasonCode (string) --
A code that explains the resolution outcome. This value is present only after the report reaches the terminal COMPLETED status; it is absent while the report is QUEUED or PROCESSING.
nextToken (string) --
The pagination token for the next page of results. This value is null when there are no more results.