Skip to content
Logs
Visit Logs on GitHub
Set theme to dark (⇧+D)

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:

ParameterDescriptionApplies toRequired?
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/receivedYes
end

- Exclusive

- Same format as start

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

/logs/receivedYes
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/receivedNo
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/receivedNo
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.