Logs Endpoint

Overview

While the built-in logs viewer displays recent log entries, for issues of compliance or advanced analysis it can be helpful to have access to the raw blocked request logs.

Important Notes

Only blocked requests are available through the API
Request data is not loaded into this log analysis system in real time. There is a variable delay based upon overall network traffic load.
Maximum date range per query is 90 days.

GET /api/logs/query

Used to create an initial request of the logs endpoint. The JSON response will contain a _scroll_id value which can then be used to page through the remaining results.

Required Parameters

Parameter	Description
`api_key`	Your API key
`start_date`	Start date in YYYY-MM-DD format
`end_date`	End date in YYYY-MM-DD format

Optional Parameters

Parameter	Description
`per_page`	Number of entries per page (default: 10,000, max: 10,000)

Request Format

GET /api/logs/query?api_key=example-api-key&start_date=2024-08-24&end_date=2024-08-25

Response - HTTP 200 - application/json

The endpoint will return a JSON response that contains the first 10,000 log entries.

Notable data elements in the response:

_scroll_id - this value represents where the data set “left off” if it extends beyond 10,000 rows. To page through all of the logs within the date range you would take this value and pass it to the /api/logs/scroll endpoint documented below.
hits['total']['value'] - this is the number of log entries within the query range. If it’s less than 10,000 the response contains all of the log entries within that range. If it’s greater than 10,000 you will need to use the /api/logs/scroll endpoint to page through the remaining log entries.
hits['hits'] - An array of log entry objects

Example Response

For space constraints the following response is truncated.

{
  "_scroll_id": "eyJzb3VyY2UiOiJwb3N0Z3Jlcy...",
  "hits": {
    "total": {
      "value": 5844
    },
    "hits": [
      {
        "timestamp": "2024-08-25T15:30:45Z",
        "client_ip": "203.0.113.42",
        "http_method": "GET",
        "request_path": "/wp-login.php",
        "http_status": 403,
        "response_size": 1024,
        "referrer": "https://example.com",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
        "block_reason": "BLOCK 1",
        "country": "US",
        "cache_hit": false
      },
      {
        "timestamp": "2024-08-25T15:28:12Z",
        "client_ip": "198.51.100.7",
        "http_method": "POST",
        "request_path": "/xmlrpc.php",
        "http_status": 403,
        "response_size": 512,
        "referrer": null,
        "user_agent": "curl/7.68.0",
        "block_reason": "BLOCK 2",
        "country": "DE",
        "cache_hit": false
      }
    ]
  }
}

Log Entry Fields

Field	Description
`timestamp`	ISO 8601 timestamp of the request
`client_ip`	IP address of the requesting client
`http_method`	HTTP method (GET, POST, etc.)
`request_path`	Requested URL path
`http_status`	HTTP response status code
`response_size`	Response body size in bytes
`referrer`	HTTP Referer header value
`user_agent`	Client User-Agent string
`block_reason`	WAF block reason code, or "NONE" if not blocked
`country`	Two-letter country code of the client
`cache_hit`	Whether the response was served from cache

GET /api/logs/scroll

Used to page through additional sets of 10,000 log records within the queried date range. You must call /api/logs/query first, retrieve the _scroll_id value from the JSON response and then use that value to call this endpoint.

Required Parameters

Parameter	Description
`api_key`	Your API key
`scroll_id`	The `_scroll_id` value from the previous response. Note: the parameter name is `scroll_id` (no leading underscore) but the value returned in the JSON response is `_scroll_id` (leading underscore).

Request Format

GET /api/logs/scroll?api_key=example-api-key&scroll_id=example-scroll-id

Response - HTTP 200 - application/json

The response to this endpoint is identical to the response from /api/logs/query . When _scroll_id is null , all results have been returned.

Note: a new _scroll_id value is returned in each response so it’s necessary to serially work through the responses.

Error Responses

Status	Condition	Example
400	Invalid date format	`{"success": false, "message": "Invalid date format. Use YYYY-MM-DD."}`
400	start_date after end_date	`{"success": false, "message": "start_date must be before or equal to end_date"}`
400	Date range exceeds 90 days	`{"success": false, "message": "Date range cannot exceed 90 days"}`
400	Invalid scroll_id	`{"success": false, "message": "Invalid scroll_id"}`
403	Missing or invalid api_key	`{"success": false, "message": "..."}`
404	No WAF configured	`{"success": false, "message": "No WAF configured for this account"}`

API Help

We’re happy to help you build whatever functionality you need with the API. Please don’t hesitate to:

Contact us at support@expeditedsecurity.com
Book a Call

We are a team of developers and sysadmins who can help troubleshoot and debug whatever API interactions you need to create.