Reporting APIs
Reporting queries can be used to fetch data from reports, for all counters under a specific group, or for a specific counter.
Synopsis |
|
|||
Supported Resource Attributes |
Duration |
This is a required parameter. All API queries should be accompanied with this parameter.
Aggregate report(s) for the specified duration.
|
||
Query Type |
|
|||
Sorting |
You should use both these parameters. If you use either, you will not receive data in the response.
|
|||
Lazy Loading |
You should use both these parameters. If you use either, you will not receive data in the response.
|
|||
Data Retrieval Option |
|
|||
Filtering |
Filter parameters restrict the data to be included the response.
|
|||
Device |
|
|||
Request Headers |
Host, Accept, Authorization |
|||
Response Headers |
Content-Type, Content-Length, Connection |
Examples
Examples for the types of reporting queries are shown below:
-
Retrieving Single Values for Each Counter in a Counter Group
-
Retrieving Multiple Values for Multiple Counters, with Multiple Values for Each Counter
-
Retrieving Top Incoming Messages that Matched a Configured Mail Policy
-
Retrieving Top Outgoing Messages that Matched a Configured Mail Policy
-
Retrieving All Incoming Messages that Matched a Configured Mail Policy
-
Retrieving All Outgoing Messages that Matched a Configured Mail Policy
Retrieving a Single Value for a Counter
This example shows a query to retrieve the value of a specific counter from a counter group, with the device name and type.
Sample Request
GET /esa/api/v2.0/reporting/mail_incoming_traffic_summary/detected_amp?
startDate=2016-09-10T19:00:00.000Z&endDate=2018-09-24T23:00:00.000Z
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive
Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Sat, 17 Nov 2018 15:58:29 GMT
Content-type: application/json
Content-Length: 96
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken
{
"meta": {
"totalCount": -1},
"data": {
"type": "detected_amp",
"resultSet": {
"detected_amp": 11}
}
}
Retrieving Multiple Values for a Counter
This example shows a query to retrieve values of all counters of a counter group, with the device group name and device type.
Sample Request
GET /esa/api/v2.0/reporting/mail_incoming_traffic_summary?startDate=2016
-09-10T19:00:00.000Z&endDate=2018-09-24T23:00:00.000Z&device_type=esa
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive
Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Sat, 17 Nov 2018 17:39:34 GMT
Content-type: application/json
Content-Length: 580
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken
{"meta": {"totalCount": -1}, "data":
{"type":
"mail_incoming_traffic_summary",
"resultSet": [{"verif_decrypt_success":5},
{"detected_virus": 13},
{"verif_decrypt_fail": 5},
{"threat_content_filter": 10},
{"total_graymail_recipients": 9},
{"blocked_invalid_recipient": 2},
{"ims_spam_increment_over_case": 0},
{"blocked_dmarc": 0},
{"blocked_sdr": 0},
{"marketing_mail": 6},
{"detected_amp": 2},
{"bulk_mail": 2},
{"total_recipients": 159},
{"social_mail": 1},
{"detected_spam": 30},
{"total_clean_recipients": 83},
{"malicious_url": 6},
{"total_threat_recipients": 67},
{"blocked_reputation": 10}]}}
Retrieving Single Values for Each Counter in a Counter Group
A counter group may have multiple counters. This example shows a query to retrieve single values for each counter in a counter group, with order, device type and top parameters.
Sample Request
GET /esa/api/v2.0/reporting/mail_content_filter_incoming/recipients
_matched?startDate=2017-09-10T19:00:00.000Z&endDate=2018-09-24T23:00:00.000Z&device_type
=esa&orderDir=desc&orderBy=recipients_matched&top=2
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive
Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Sat, 17 Nov 2018 18:17:29 GMT
Content-type: application/json
Content-Length: 153
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken
{
"meta": {
"totalCount": -1
},
"data": {
"type": "recipients_matched",
"resultSet": {
"recipients_matched": [
{"url_rep_neutral": 16},
{"url_category": 8}
]
}
}
}
Retrieving Multiple Values for Multiple Counters
This example shows a query to retrieve multiple values for multiple counters, with offset, limit and device type parameters.
Sample Request
GET /esa/api/v2.0/reporting/mail_incoming_domain_detail?startDate=2017-09-10T19:00:00.000Z
&endDate=2018-09-24T23:00:00.000Z&device_type=esa&offset=1&limit=2
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive
Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Sat, 17 Nov 2018 18:25:28 GMT
Content-type: application/json
Content-Length: 1934
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken
{
"meta": {
"totalCount": -1
},
"data": {
"type": "mail_incoming_domain_detail",
"resultSet": {
"conn_tls_total": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 5}
],
"conn_tls_opt_success": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 0}
],
"conn_tls_opt_fail": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 0}
],
"blocked_invalid_recipient": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 1}
],
"last_sender_group_name": [
{"pphosted.com": "UNKNOWNLIST"},
{"vm30bsd0004.ibqa": "UNKNOWNLIST"}
],
"detected_amp": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 2}
],
"social_mail": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 1}
],
"detected_spam": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 25}
],
"blocked_reputation": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 5}
],
"total_throttled_recipients": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 2}
],
"total_accepted_connections": [
{"pphosted.com": 2},
{"vm30bsd0004.ibqa": 119}
],...
...
"threat_content_filter": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 5}
],
"marketing_mail": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 5}
],
"blocked_dmarc": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 0}
],
"conn_tls_success": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 5}
],
"total_recipients": [
{"pphosted.com": 2},
{"vm30bsd0004.ibqa": 112}
],
"conn_tls_fail": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 0}
],
"total_threat_recipients": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 49}
]
}
}
}
Retrieving Multiple Values for Multiple Counters, with Multiple Values for Each Counter
This example shows a query to retrieve multiple values for multiple counters (with multiple values for each counter), with filtering, and query type parameters. The graph attribute retrieves time based counter values of counters.
Sample Request
GET /esa/api/v2.0/reporting/mail_incoming_ip_hostname_detail?startDate=
2017-09-10T19:00:00.000Z&endDate=2018-09-24T23:00:00.000Z&device_type=esa&filterBy
=ip_address&filterOperator=begins_with&filterValue=10&query_type=graph
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive
Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Sat, 17 Nov 2018 18:49:42 GMT
Content-type: application/json
Content-Length: 74110
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken
{
"meta": {
"totalCount": -1
},
"data": {
"type": "mail_incoming_ip_hostname_detail",
"resultSet": {
"dns_verified": {
"10.76.68.103": [
{"2017-09-01T00:00:00.000Z to 2017-09-30T23:59:00.000Z": 2},
{"2017-10-01T00:00:00.000Z to 2017-10-31T23:59:00.000Z": 1},
...
...
{"2018-09-01T00:00:00.000Z to 2018-09-30T23:59:00.000Z": 1}
],
"10.76.71.211": [
{"2017-09-01T00:00:00.000Z to 2017-09-30T23:59:00.000Z": 1},
{"2017-10-01T00:00:00.000Z to 2017-10-31T23:59:00.000Z": 3},
...
...
{"2017-11-01T00:00:00.000Z to 2017-11-30T23:59:00.000Z": 1},
{"2017-12-01T00:00:00.000Z to 2017-12-31T23:59:00.000Z": 0}
],
},
{
"2018-09-01T00:00:00.000Z to 2018-09-30T23:59:00.000Z": 0
}
]
},
"last_sender_group": {
"10.76.68.103": [
{"2017-09-01T00:00:00.000Z to 2017-09-30T23:59:00.000Z": 4},
{"2018-08-01T00:00:00.000Z to 2018-08-31T23:59:00.000Z": 0},
}
],
"10.76.71.211": [
{"2017-09-01T00:00:00.000Z to 2017-09-30T23:59:00.000Z": 2},
{"2017-10-01T00:00:00.000Z to 2017-10-31T23:59:00.000Z": 2},
}
]
},
"total_threat_recipients": {
"10.76.68.103": [
{"2017-09-01T00:00:00.000Z to 2017-09-30T23:59:00.000Z": 2},
{"2017-10-01T00:00:00.000Z to 2017-10-31T23:59:00.000Z": 20},
...
...
{"2018-08-01T00:00:00.000Z to 2018-08-31T23:59:00.000Z": 0},
}
]
},
"threat_content_filter": {
"10.76.68.103": [
{"2017-09-01T00:00:00.000Z to 2017-09-30T23:59:00.000Z": 0},
{"2017-10-01T00:00:00.000Z to 2017-10-31T23:59:00.000Z": 1},
...
...
}
]
},
"total_graymail_recipients": {
"10.76.68.103": [
{"2017-09-01T00:00:00.000Z to 2017-09-30T23:59:00.000Z": 0},
{"2017-10-01T00:00:00.000Z to 2017-10-31T23:59:00.000Z": 4},
...
...
{"2018-08-01T00:00:00.000Z to 2018-08-31T23:59:00.000Z": 0},
{"2018-09-01T00:00:00.000Z to 2018-09-30T23:59:00.000Z": 0}
]
},
"total_clean_recipients": {
"10.76.68.103": [
{"2018-08-01T00:00:00.000Z to 2018-08-31T23:59:00.000Z": 5},
{"2018-09-01T00:00:00.000Z to 2018-09-30T23:59:00.000Z": 0}
]
},
"sbrs_score": {
"10.76.68.103": [
{"2017-09-01T00:00:00.000Z to 2017-09-30T23:59:00.000Z": 3},
...
...
{"2018-08-01T00:00:00.000Z to 2018-08-31T23:59:00.000Z": 0},
{"2018-09-01T00:00:00.000Z to 2018-09-30T23:59:00.000Z": 0}
]
},
"blocked_reputation": {
"10.76.68.103": [
{"2017-09-01T00:00:00.000Z to 2017-09-30T23:59:00.000Z": 0},
]
}
}
}
}
Retrieving Top Incoming Messages that Matched a Configured Mail Policy
The following example shows a query to retrieve the top incoming messages that matched a configured mail policy in your email gateway.
Sample Request
GET /esa/api/v2.0/reporting/mail_policy_incoming/recipients_matched?
device_type=esa&endDate=2021-02-26T14:00:00.000Z&startDate=2020-11-27T18:00:00.000Z&top=10
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46Q2lzY28xMjMk
Accept: application/json, text/plain, */*
Host: esa.example.com:6080
accept-encoding: gzip, deflate, br
accept-language: en-US,en;q=0.9
connection: keep-alive
Sample Response
HTTP/1.0 200 OK
Server: API/2.0
Date: Thu, 12 Sept 2019 14:17:44 GMT
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS, PUT
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Content-Disposition, jwtToken
Cache-control: no-store
Connection: keep-alive
Content-Length: 435
Content-Type: application/json; charset=UTF-8
{
"meta": {
"totalCount": -1
},
"data": {
"type": "recipients_matched",
"resultSet": {
"recipients_matched": [
{
"Bypass_Blocklist_Policy": 318172
},
{
"Test Mail Policy Marketing2Junk": 177994
},
{
"DEFAULT": 147011
},
{
"Allow Marketing Newsletters": 28882
},
{
"Aggressive Spam Scoring": 18605
},
{
"Allowed_listEmailAddresses": 15177
},
{
"ampuser": 9463
},
{
"Block_Inbound_Mail_Westfield": 9436
},
{
"Bulk Mail Quarantined": 9365
},
{
"virususer": 9238
}
]
}
}
}
Retrieving Top Outgoing Messages that Matched a Configured Mail Policy
The following example shows a query to retrieve the top outgoing messages that matched a configured mail policy in your email gateway.
Sample Request
GET /esa/api/v2.0/reporting/mail_policy_outgoing/recipients_matched?
device_type=esa&endDate=2021-02-26T14:00:00.000Z&startDate=2020-11-27T18:00:00.000Z&top=10
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46Q2lzY28xMjMk
Accept: application/json, text/plain, */*
Host: esa.example.com:6080
Accept-Encoding: gzip, deflate, br
Accept-Language: en-US,en;q=0.9
Connection: keep-alive
Sample Response
HTTP/1.0 200 OK
Server: API/2.0
Date: Thu, 12 Sept 2019 14:17:44 GMT
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS, PUT
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Content-Disposition, jwtToken
Cache-control: no-store
Connection: keep-alive
Content-Length: 163
Content-Type: application/json; charset=UTF-8
{
"meta": {
"totalCount": -1
},
"data": {
"type": "recipients_matched",
"resultSet": {
"recipients_matched": [
{
"Block_Outbound_Traffic": 921281
},
{
"DEFAULT": 23623
}
]
}
}
}
Retrieving All Incoming Messages that Matched a Configured Mail Policy
The following example shows a query to retrieve all incoming messages that matched a configured mail policy in your email gateway.
Sample Request
GET /esa/api/v2.0/reporting/mail_policy_incoming/recipients_matched?
device_type=esa&endDate=2021-02-26T14:00:00.000Z&limit=25&offset=0&startDate=2020-11-27T18:00:00.000Z
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46Q2lzY28xMjMk
Accept: application/json, text/plain, */*
Host: esa.example.com:6080
Accept-Encoding: gzip, deflate, br
Accept-Language: en-US,en;q=0.9
Connection: keep-alive
Sample Response
HTTP/1.0 200 OK
Server: API/2.0
Date: Thu, 12 Sept 2019 14:17:44 GMT
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS, PUT
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Content-Disposition, jwtToken
Cache-control: no-store
Connection: keep-alive
Content-Length: 547
Content-Type: application/json; charset=UTF-8
{
"meta": {
"totalCount": -1
},
"data": {
"type": "recipients_matched",
"resultSet": {
"recipients_matched": [
{
"Bypass_Blocklist_Policy": 318172
},
{
"Test Mail Policy Marketing2Junk": 177994
},
{
"DEFAULT": 147011
},
{
"Allow Marketing Newsletters": 28882
},
{
"Aggressive Spam Scoring": 18605
},
{
"Allowed_listEmailAddresses": 15177
},
{
"ampuser": 9463
},
{
"Block_Inbound_Mail_Westfield": 9436
},
{
"Bulk Mail Quarantined": 9365
},
{
"virususer": 9238
},
{
"Allow_Marketing_Filter_Spam": 4651
},
{
"Blocklist Email Addresses": 847
},
{
"second-selva": 12
},
{
"second": 2
}
]
}
}
}
Retrieving All Outgoing Messages that Matched a Configured Mail Policy
The following example shows a query to retrieve all outgoing messages that matched a configured mail policy in your email gateway.
Sample Request
GET /esa/api/v2.0/reporting/mail_policy_outgoing/recipients_matched?
device_type=esa&endDate=2021-02-26T14:00:00.000Z&limit=25&offset=0&startDate=2020-11-27T18:00:00.000Z
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46Q2lzY28xMjMk
Accept: application/json, text/plain, */*
Host: esa.example.com:6080
Accept-Encoding: gzip, deflate, br
Accept-Language: en-US,en;q=0.9
Connection: keep-alive
Sample Response
HTTP/1.0 200 OK
Server: API/2.0
Date: Thu, 12 Sept 2019 14:17:44 GMT
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS, PUT
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Content-Disposition, jwtToken
Cache-control: no-store
Connection: keep-alive
Content-Length: 163
Content-Type: application/json; charset=UTF-8
{
"meta": {
"totalCount": -1
},
"data": {
"type": "recipients_matched",
"resultSet": {
"recipients_matched": [
{
"Block_Outbound_Traffic": 921281
},
{
"DEFAULT": 23623
}
]
}
}
}