Requesting logs

Endpoints

The three endpoints the Logpull API supports are:

  • GET /logs/received - returns HTTP request log data based on the parameters specified
  • GET /logs/received/fields - returns the list of all available log fields
  • GET /logs/rayids/<rayid> - returns HTTP request log data matching <rayid>

Required authentication headers

The following headers are required for all endpoint calls:

  • X-Auth-Email - the Cloudflare account email address associated with the domain
  • X-Auth-Key - the Cloudflare API key

Parameters

The API expects endpoint parameters in the GET request query string. See the example formats below.

logs/received

https://api.cloudflare.com/client/v4/zones/<zone_id>/logs/received?start=<unix|rfc3339>&end=<unix|rfc3339>[&count=<int>][&sample=<float>][&fields=<fields>][&timestamps=<string>]

logs/rayids/<rayid>

https://api.cloudflare.com/client/v4/zones/<zone_id>/logs/rayids/<ray_id>?[&fields=<string>][&timestamps=<strings>]

The following table describes the parameters available:

Parameter Description Applies to Required?
start

- Inclusive

- Timestamp formatted as UNIX (UTC by definition), UNIX Nano, or rfc3339 (specifies time zone)

- Must be no more than 7 days earlier than now

/logs/received Yes
end

- Exclusive

- Same format as start

- Must be at least 1 minute earlier than now and later than start

/logs/received Yes
count

- Return up to that many records

- Do not include if returning all records

- Results are not sorted; therefore, different data for repeated requests is likely

- Applies to number of total records returned, not number of sampled records

/logs/received No
sample

- Return only a sample of records

- Do not include if returning all records

- Value can range from 0.001 to 1.0 (inclusive)

- sample=0.1 means return 10% (1 in 10) of all records

- Results are random; therefore, different numbers of results for repeated requests are likely

/logs/received No
fields

- Comma-separated list of fields to return

- If empty, the default list is returned

/logs/received

/logs/rayids

No
timestamps

- Format in which timestamp fields will be returned

- Value options are: unixnano (default), unix, rfc3339

- Timestamps retuned as integers for unix and unixnano and as strings for rfc3339

/logs/received

/logs/rayids

No

The maximum time range from start to end can’t exceed 1 hour. Because start is inclusive and end is exclusive, to get all the data for every minute, starting at 10AM, the proper values are:

start=2018-05-15T10:00:00Z&end=2018-05-15T10:01:00Z, then start=2018-05-15T10:01:00Z&end=2018-05-15T10:02:00Z and so on.

The overlap will be handled correctly.

Example API requests using cURL

logs/received

curl -s \
    -H "X-Auth-Email: <REDACTED>" \
    -H "X-Auth-Key: <REDACTED>" \
    "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/logs/received?start=2017-07-18T22:00:00Z&end=2017-07-18T22:01:00Z&count=1&fields=RayID,ClientIP"

logs/rayids

curl -s \
    -H "X-Auth-Email: <REDACTED>" \
    -H "X-Auth-Key: <REDACTED>" \
    "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/logs/rayids/47ff6e2c812d3ccb?timestamps=rfc3339"

The IATA code returned as part of the Ray ID does not need to included in the request. For example: if you have a RayID such as 49ddb3e70e665831-DFW only include 49ddb3e70e665831 in your request.

Fields

Unless specified in the fields parameter, the API returns a limited set of log fields. This default field set may change at any time. The list of all available fields is at:

https://api.cloudflare.com/client/v4/zones/<zone_id>/logs/received/fields

The order in which fields are specified doesn’t matter, and the order of fields in the response is not specified.

Using Bash subshell and jq, you can download the logs with all available fields without manually copying and pasting the fields into the request. For example:

curl -s \
    -H "X-Auth-Email: <REDACTED>" \
    -H "X-Auth-Key: <REDACTED>" \
    "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/logs/received?start=2017-07-18T22:00:00Z&end=2017-07-18T22:01:00Z&count=1&fields=$(curl -s -H "X-Auth-Email: <REDACTED>" -H "X-Auth-Key: <REDACTED>" "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/logs/received/fields" | jq '. | to_entries[] | .key' -r | paste -sd "," -)"

The table below summarizes the fields currently available:

Field Value Type
CacheCacheStatus unknown | miss | expired | updating | stale | hit | ignored | bypass | revalidated string
CacheResponseBytes Number of bytes returned by the cache int
CacheResponseStatus
HTTP status code returned by the cache to the edge; all requests (including non-cacheable ones) go through the cache; also see CacheStatus field
int
CacheTieredFill Tiered Cache was used to serve this request bool
ClientASN Client AS number int
ClientCountry Country of the client IP address string
ClientDeviceType Client device type string
ClientIP IP address of the client string
ClientIPClass
unknown | clean | badHost | searchEngine | whitelist | greylist | monitoringService | securityScanner | noRecord | scan | backupService | mobilePlatform | tor
string
ClientRequestBytes Number of bytes in the client request int
ClientRequestHost Host requested by the client string
ClientRequestMethod HTTP method of client request string
ClientRequestPath URI path requested by the client string
ClientRequestProtocol HTTP protocol of client request string
ClientRequestReferer HTTP request referrer string
ClientRequestURI URI requested by the client string
ClientRequestUserAgent User agent reported by the client string
ClientSSLCipher Client SSL cipher string
ClientSSLProtocol Client SSL (TLS) protocol string
ClientSrcPort Client source port int
EdgeColoCode Airport code of data center that received the request string
EdgeColoID Cloudflare edge colo id int
EdgeEndTimestamp Timestamp when the edge finished sending response to the client timestamp
EdgePathingOp Indicates what type of response was issued for this request (unknown = no specific action) string
EdgePathingSrc Details how the request was classified based on security checks (unknown = no specific classification) string
EdgePathingStatus Indicates what data was used to determine the handling of this request (unknown = no data) string
EdgeRateLimitAction The action taken by the blocking rule; empty if no action taken string
EdgeRateLimitID The internal rule ID of the rate-limiting rule that triggered a block (ban) or simulate action. 0 if no action taken int
EdgeRequestHost Host header on the request from the edge to the origin string
EdgeResponseBytes Number of bytes returned by the edge to the client int
EdgeResponseCompressionRatio
Edge response compression ratio float
EdgeResponseContentType Edge response Content-Type header value string
EdgeResponseStatus HTTP status code returned by Cloudflare to the client int
EdgeServerIP IP of the edge server making a request to the origin string
EdgeStartTimestamp Unix nanosecond timestamp the edge received request from the client timestamp
FirewallMatchesActions Array of actions the Cloudflare firewall products performed on this request. The individual firewall products associated with this action be found in FirewallMatchesSources and their respective RuleIds can be found in FirewallMatchesRuleIDs. The length of the array is the same as FirewallMatchesRuleIDs and FirewallMatchesSources.
Possible actions are allow | log | simulate | drop | challenge | jschallenge | connectionClose
array of actions (strings)
FirewallMatchesSources The firewall products that matched the request. The same product can appear multiple times, which indicates different rules or actions that were activated. The RuleIDs can be found in FirewallMatchesRuleIDs, the actions can be found in FirewallMatchesActions. The length of the array is the same as FirewallMatchesRuleIDs and FirewallMatchesActions.
Possible sources are asn | country | ip | ipRange | securityLevel | zoneLockdown | waf | firewallRules | uaBlock | rateLimit | bic | hot | l7ddos
array of product names (strings)
FirewallMatchesRuleIDs Array of RuleIDs of the firewall product that has matched the request. The firewall product associated with the RuleID can be found in FirewallMatchesSources. The length of the array is the same as FirewallMatchesActions and FirewallMatchesSources.
array of RuleIDs (strings)
OriginIP IP of the origin server string
OriginResponseBytes (deprecated) Number of bytes returned by the origin server int
OriginResponseHTTPExpires Value of the origin 'expires' header in RFC1123 format timestamp
OriginResponseHTTPLastModified
Value of the origin 'last-modified' header in RFC1123 format timestamp
OriginResponseStatus Status returned by the origin server int
OriginResponseTime Number of nanoseconds it took the origin to return the response to edge int
OriginSSLProtocol SSL (TLS) protocol used to connect to the origin string
ParentRayID Ray ID of the parent request if this request was made using a Worker script string
RayID ID of the request string
SecurityLevel The security level configured at the time of this request. This is used to determine the sensitivity of the IP Reputation system string
WAFAction Action taken by the WAF, if triggered string
WAFFlags Additional configuration flags: simulate (0x1) | null string
WAFMatchedVar The full name of the most-recently matched variable string
WAFProfile low | med | high string
WAFRuleID ID of the applied WAF rule string
WAFRuleMessage Rule message associated with the triggered rule string
WorkerCPUTime Amount of time in microseconds spent executing a worker, if any int
WorkerStatus Status returned from worker daemon string
WorkerSubrequest Whether or not this request was a worker subrequest bool
WorkerSubrequestCount Number of subrequests issued by a worker when handling this request int
ZoneID Internal zone ID int