Query Action Results | Trend Micro Service Central

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

Important:

The 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: If both `start` and `end` are not specified, the request retrieves logs within five minutes before the point of time when the request is sent. If both `start` and `end` are specified, the request retrieves logs within the configured duration. Make sure the end time is no earlier than the start time. If only `start` is specified, the request retrieves logs within five minutes after the point of the configured start time. If only `end` is specified, the request retrieves logs within five minutes before the point of the configured end time.
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.

Note:

All 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: Created: The API request containing the action is received. Executing: The action is being processed. Success: The action is successfully taken. Skipped: The action is skipped for certain reason. For example, the same action was requested twice. Failed: The action fails.
`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: 0 200 -100 -101 -102 -104 -999 -410 -411 -412 Note: Error codes -410, -411, and -412 are applicable to Exchange Online only.
`actions/error_message`	String	String describing the result code. Options corresponding to each error code include: 0: success 200: The user is already disabled. -100: The service account could not be found. -101: The service account is not valid. -102: The access token could not be found. -104: Failed to connect to EWS. -999: An unknown error has occurred. -410: The email message could not be found. -411: The email message is already quarantined. -412: The email message is already deleted.