Requesting logs
The three endpoints supported by the Logpull API 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/{ray_id}- returns HTTP request log data matching{ray_id}
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
Alternatively, API tokens with Logs Read permissions can also be used for authentication:
Authorization: Bearer <API_TOKEN>
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>][×tamps=<string>][&CVE-2021-44228=<boolean>]logs/rayids/{ray_id}
https://api.cloudflare.com/client/v4/zones/{zone_id}/logs/rayids/{ray_id}?[&fields=<FIELDS>][×tamps=<string>]The following table describes the parameters available:
| Parameter | Description | Applies to | Required |
|---|---|---|---|
| start | - Inclusive - Timestamp formatted as - 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 - - 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: - Timestamps returned as integers for | /logs/received /logs/rayids | No |
| CVE-2021-44228 | - Optional redaction for CVE-2021-44228 ↗. This option will replace every occurrence of the string For example: | /logs/received | No |
logs/received
curl "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" \--header "X-Auth-Email: <EMAIL>" \--header "X-Auth-Key: <API_KEY>"logs/rayids/{ray_id}
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/logs/rayids/{ray_id}}?timestamps=rfc3339" \--header "X-Auth-Email: <EMAIL>" \--header "X-Auth-Key: <API_KEY>"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:
FIELDS=$(curl https://api.cloudflare.com/client/v4/zones/{zone_id}/logs/received/fields \--header "X-Auth-Email: <EMAIL>" \--header "X-Auth-Key: <API_KEY>" \| jq '. | to_entries[] | .key' -r | paste -sd "," -)
curl "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=$FIELDS" \--header "X-Auth-Email: <EMAIL>" \--header "X-Auth-Key: <API_KEY>"Refer to Download jq ↗ for more information on obtaining and installing jq.
Refer to HTTP request fields for the currently available fields.