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 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-aliveSample 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-aliveSample 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},
,
{"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-aliveSample 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-aliveSample 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-aliveSample 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},
]
}
}
}
}
Feedback