Requesting logs
Endpoints
The three endpoints the Logpull API supports are:
GET /logs/received- returns HTTP request log data based on the parameters specifiedGET /logs/received/fields- returns the list of all available log fieldsGET /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 domainX-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>][×tamps=<string>]
logs/rayids/<rayid>
https://api.cloudflare.com/client/v4/zones/<zone_id>/logs/rayids/<ray_id>?[&fields=<string>][×tamps=<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 |
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"
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 "," -)"
See HTTP request fields for the currently available fields.