Queries the results of actions on specified email messages or user accounts
through Take Actions on User Accounts and Take Actions on Email Messages APIs.
HTTPS Request
-
To query action results of user accounts:
GET https://<serviceURL>/v1/mitigation/accounts
-
To query action results of email messages:
GET https://<serviceURL>/v1/mitigation/mails
Request Parameters
 |
ImportantThe request must contain the required parameters.
|
|
Parameter
|
Description
|
|
Required Parameter
|
|
batch_id |
Unique ID of a Threat Mitigation API request
To query actions taken within a single request, use this parameter.
|
start
end |
Start and end time during which action results are to retrieve.
Format: ISO 8601 timestamp to the second or millisecond in UTC,
yyyy-mm-ddThh:mm:ss[.mmm]Z. For example,
2016-07-22T01:51:31Z or
2016-07-22T01:51:31.001Z.
The request retrieves logs within a maximum of 72 hours before the point of time
when the request is sent according to the
start and
end settings:
|
|
Optional Parameter
|
|
limit |
Number of action results to display at a time. A maximum of 500 are
allowed
If not specified, the value is set to 500 by default.
If the total action results requested exceed the specified limit, a
URL is provided in the next_link field in the response. Use
this URL to form a second request to retrieve the remaining action results for the
previous request. Repeat this until all action results for the first request are
obtained.
|
Request Example
Example 1: retrieve the results of actions taken on user accounts within a
single
request
GET https://api.tmcas.trendmicro.com/v1/mitigation/accounts?batch_id=b97d5470-3bec-11e9-b842-158f7dd62a77 Authorization: Bearer 1de231142eef3f83928da98dc251fbebb6cafe77
Example 2: retrieve the results of actions taken on email messages from
2019-03-19 03:35:07.000 to 2019-03-19 05:47:07:000 (UTC), with the number of items
to
display at a time being 10
GET https://api.tmcas.trendmicro.com/v1/siem/mails?start=2019-03-19T03:35:07.000Z&end=2019-03-19T05:47:07.000Z&limit=10 Authorization: Bearer 1de231142eef3f83928da98dc251fbebb6cafe77
Response
On success, the service sends back an HTTP 200 response and returns a response
body in JSON format; otherwise, the service sends back an error message in JSON format
with
error details. For more information about errors, see API Responses.
Response Example
HTTP/1.1 200
Content-Type: application/json
{
"count": 1,
"current_link": "https://api.tmcas.trendmicro.com/v1/mitigation/accounts?batch_id=228ab860-46cc-11e9-8071-ff4462689877&limit=1",
"next_link": "https://api.tmcas.trendmicro.com/v1/mitigation/accounts?batch_id=228ab860-46cc-11e9-8071-ff4462689877&limit=1&&offset=01",
"actions": [
{
"action_type": "ACCOUNT_DISABLE",
"service": "exchange",
"account_provider": "office365",
"account_user_email": "user@example.com",
"action_id": "24e9de10-46cc-11e9-8071-ff4462689877",
"batch_id": "228ab860-46cc-11e9-8071-ff4462689877",
"status": "Success",
"action_requested_at": "2019-03-04T06:30:21.613Z",
"action_executed_at": "2019-03-04T06:30:21.613Z",
"error_code": 0,
"error_message": "success"
}
]
}
Response Fields
The following table describes the available fields for the response body.
 |
NoteAll time-related fields in the table are set to Coordinated Universal Time
(UTC).
|
|
Field
|
Data Type
|
Description
|
||
count |
Integer
|
Number of action results returned in the current response
|
||
current_link |
String
|
URL in the current request
|
||
next_link |
String
|
URL for the follow-up request if the requested action results exceed
the specified limit to display at a time. Use this URL to form a second request to
retrieve the remaining action results for the previous request. Repeat this until
all action results for the first request are obtained.
|
||
actions |
JSON array
|
Details of the requested action results
|
||
actions/action_type |
String
|
Action taken on an email message or user account
|
||
actions/service |
String
|
Name of the protected service to which the API applied
|
||
actions/account_provider |
String
|
Provider of the protected service
|
||
actions/account_user_email |
String
|
Email address used to create the user account on which an action was
taken
|
||
actions/mailbox |
String
|
Email address of an email message on which an action was taken
|
||
actions/mail_message_id |
String
|
Internet message ID of an email message on which an action was
taken
|
||
actions/mail_unique_id |
String
|
Unique ID of an email message on which an action was taken
|
||
actions/action_id |
String
|
Unique ID of a threat mitigation task
|
||
actions/batch_id |
String
|
Unique ID of a Threat Mitigation API request
|
||
actions/status |
String
|
Status of an action taken. Options include:
|
||
actions/action_requested_at |
ISO 8601 timestamp
|
Date and time when the API request containing the action was
received
|
||
actions/action_executed_at |
ISO 8601 timestamp
|
Date and time when the action was processed
|
||
actions/error_code |
Integer
|
Result code of the action. Options include:
|
||
actions/error_message |
String
|
String describing the result code. Options corresponding to each
error code include:
|