Cloudflare Docs
Logs
Cloudflare Docs
Logs
GitHub icon
Visit Logs on GitHub
Set theme to dark (⇧+D)
  1. Products
  2. Logs
  3. Logpull
  4. Requesting logs

Requesting logs

​​ Endpoints

The three endpoints supported by the Logpull API 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

Alternatively, API tokens with Logs Edit permissions can also be used for authentication:

  • Authorization: Bearer <API_TOKEN>

​​ Parameters

The API expects endpoint parameters in the GET request query string. The following are example formats:

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>][&CVE-2021-44228=<boolean>]

logs/rayids/<RAY_ID>

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 returned as integers for unix and unixnano and as strings for rfc3339

/logs/received

/logs/rayids

No
CVE-2021-44228

- Optional redaction for CVE-2021-44228. This option will replace every occurrence of the string ${ with x{.

For example: CVE-2021-44228=true

/logs/received

No

​​ Example API requests using cURL

logs/received

curl -s \
    -H "X-Auth-Email: <EMAIL>" \
    -H "X-Auth-Key: <API_KEY>" \
    "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=ClientIP,ClientRequestHost,ClientRequestMethod,ClientRequestURI,EdgeEndTimestamp,EdgeResponseBytes,EdgeResponseStatus,EdgeStartTimestamp,RayID"

logs/rayids/<RAY_ID>

curl -s \
    -H "X-Auth-Email: <EMAIL>" \
    -H "X-Auth-Key: <API_KEY>" \
    "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 does not 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: <EMAIL>" \
    -H "X-Auth-Key: <API_KEY>" \
    "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: <EMAIL>" -H "X-Auth-Key: <API_KEY>" "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/logs/received/fields" | jq '. | to_entries[] | .key' -r | paste -sd "," -)"

Refer to HTTP request fields for the currently available fields.