Delivery Stats

Stats

Provides methods to retrieve aggregated access log stats from your web traffic through our service.

GET /stats/data

Returns aggregated access log stats information as a JSON response

Used to make specific queries against the aggregated statistics. See the Delivery Stats API Guide for details.

Parameters

ParameterDescriptionParameter TypeData Type
dimensions

Comma-separated list of access log fields over which the aggregation has been performed

query stringstring
metrics

Comma-separated list of access log fields which represent the aggregated log metrics


query stringstring
granularity

String denoting the granularity of the aggregated access log data to retrieve

query stringstring
sortByComma-separated list of dimensions and metrics over which the stats data should be sortedquery stringstring
filters

Comma-separated list of boolean expressions that restrict the data returned for your request

query stringstring
starttime

ISO 8601 time indicating the start time of the desired range of stats data

query stringstring
endtimeISO 8601 time indicating the end time of the desired range of stats dataquery stringstring
start

The first row of data to retrieve, starting from 0

query stringinteger
limit

The number of data points of the stats data desired

query stringinteger

Response Messages

HTTP Status CodeResponse Model
200A JSON response structure containing stats data in rows along with query metadata
400If invalid query parameters were provided.
defaultSuccess

GET /stats/dimensions

Returns list of valid dimensions of the aggregated access log stats data. A valid combination of dimensions forms a grouping set that is used to query the aggregated stats data using the GET /stats/data query.

Response Messages

HTTP Status CodeResponse Model
200A JSON response structure containing the list of the valid dimensions of the aggregated access log stats data 
defaultSuccess

GET /stats/groupings

Returns the list of the valid grouping sets of the various dimensions present in the aggregated access log stats data. The grouping sets are of the following format:

<dimension1>/<dimension2>/<dimension3>.../<dimensionn>

Response Messages

HTTP Status CodeResponse Model
200A JSON response structure containing the list of the valid grouping sets of the various dimensions of the aggregated access log stats data
defaultSuccess

GET /stats/metrics

Returns the list of the valid metrics of the aggregated access log stats data. One or metrics can then be supplied to the GET /stats/data query to retrieve the aggregated stats data.

Response Messages

HTTP Status CodeResponse Model
200A JSON response structure containing the list of the valid metrics of the distinct count stats data 
defaultSuccess

topK URLs

These methods provide data on the top 20 (k=20) URLs based on the aggregated delivery data.

GET /stats/topk/url/data

This provides data on the top 20 URLs for supported dimension groupings. You specify a time span and a list of the dimensions and metrics you want. You can optionally filter out some of the data you receive by adding an optional filter parameter to the query string.

See the Delivery Stats API Guide for details.

The query structure for each is appended to the API URL as a standard query string, as follows:

https://api.instartlogic.com/<your unique customer name>/v1/stats/topk/<category>/data?
dimensions=<dimension1,dimension2...>
&metrics=hits
&startime=<UTC date/time of the desired beginning time>
&endtime=<UTC date/time of the desired end time>
&granularity=day
[&filters=<filter expression 1,...>]

where filters is optional, and its form is described above under the "Statistics queries" section above.

Note

  • The results are inclusive for starttime but exclusive of endtime. That is, a timespan of 8am on one day to 8am of the next will include hits that occur at 8:00:00am of the first day through 7:59:59am of the next.
  • If your time span is greater than one day, the query returns 20 results for each day.
  • If your filters are too selective you can possibly receive fewer than 20 results.

HEAD /stats/topk/url

The HEAD method is identical to GET except that the server doesn't return a message body in the response, just the same headers. This is useful for testing hypertext links for validity, accessibility, and recent modification.

GET /stats/topk/url/dimensions

This provides a list of the available dimensions of the aggregated summary security trend data.

The available dimensions are

  • content_type
  • request_type
  • http_status_code
  • property
  • request_url
  • customer

GET /stats/topk/<category>/groupings

The groupings method returns the list of the valid dimension groupings of the aggregated security trend statistics. Only these combinations of dimensions can be used in querying for topk URL data.

The valid groupings are

  • customer/property/request_type/http_status_code/request_url
  • customer/property/content_type/request_url
  • customer/property/request_url

GET /stats/topk/url/metrics

The metrics method returns the list of the valid metrics of the aggregated security trend statistics.

Metrics are quantitative measurements. Currently, the only metric available is hits.

Some query examples

The following are some examples of using the delivery stats API to query for statistics. Line breaks are added for readability.

If you use cURL, execute the command

curl -v -u 'username:password' '<base URL>?<query string>'

If you use Postman or a similar REST client:

  1. Open a new Request window.
  2. In the URL field at the top enter the base URL and the query string.
  3. Select GET from the method list to the left of the URL field.
  1. Below, in the Authorization tab, select Basic Auth from the Type list, and enter your Username and Password in the fields provided.
  2. Click Send.

With either method you would of course use your own authorization string and company name in place of the placeholders. Also be sure that the starttime and endtime parameters cover a time span that occurred within the last three days if you are querying raw event data from the access logs.

Example 1

This request asks for the HTTP status codes, URLs, request type and property of the top 20 hits between May 30th 2018 at 8am and May 31 2018 at 8am.

The base URL and query string for this query are

https://api.instartlogic.com/acme/v1/stats/data?
dimensions=http_status_code,request_url,request_type,property
&metrics=hits
&starttime=2018-05-30T08:00:00
&endtime=2018-05-31T08:00:00

If successful the API server will respond with a JSON object similar to the following (for brevity only a few rows are shown of the full number actually returned):

{
 "query": {
   "starttime": "2018-05-30T08:00:00",
   "endtime": "2018-05-31T08:00:00",
   "start": 0,
   "limit": 20,
   "dimensions": [
     "http_status_code",
     "request_url",
     "request_type",
     "property"
   ],
   "sortby": [
     "-hits"
   ],
   "metrics": [
     "hits"
   ],
   "granularity": "day",
   "filters": "customer==acme"
 },
 "columns": [
   {
     "name": "starttime"
   },
   {
     "name": "endtime"
   },
   {
     "name": "http_status_code"
   },
   {
     "name": "request_url"
   },
   {
     "name": "request_type"
   },
   {
     "name": "property"
   },
   {
     "name": "hits"
   }
 ],
 "rows": [
   [
     "2018-05-31T00:00:00",
     "2018-06-01T00:00:00",
     "301",
     "http:\/\/www.acme.com\/",
     "HEAD",
     "public",
     20162
   ],
   [
     "2018-05-31T00:00:00",
     "2018-06-01T00:00:00",
     "200",
     "https:\/\/www.acme.com\/",
     "HEAD",
     "public",
     20116
   ],
   [
     "2018-05-31T00:00:00",
     "2018-06-01T00:00:00",
     "301",
     "http:\/\/www.acme.com\/robots.txt",
     "HEAD",
     "public",
     13766
   ],

   ...
   [
     "2018-05-31T00:00:00",
     "2018-06-01T00:00:00",
     "200",
     "https:\/\/www.acme.com\/",
     "GET",
     "public",
     13225
   ]
  ],
 "total_results": 20
}