Skip to main content

​
Overview

The Logs API provides access to HTTP request logs and other event data in real-time. Query logs by Ray ID, retrieve received logs, and manage log retention controls.

​
Initialize the client

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: 'your-api-token',
});

​
Ray ID

Lookup logs by Ray ID.

​
Get log by Ray ID

Retrieve logs for a specific Ray ID. 
const log = await client.logs.RayID.get({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  ray_id: 'abc123def456',
});
​
zone_id
string
required
Zone identifier
​
ray_id
string
required
The Ray ID to look up (found in Cloudflare error pages and headers)
​
rayId
string
The Ray ID
​
timestamp
string
Request timestamp
​
clientIP
string
Client IP address
​
request
object
Request details
​
response
object
Response details
Ray IDs are unique identifiers assigned to every request processed by Cloudflare. They’re useful for debugging specific requests and troubleshooting issues.

​
Received

Access received HTTP request logs.

​
Get received logs

Retrieve a stream of HTTP request logs. 
const logs = await client.logs.received.get({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  start: Math.floor(Date.now() / 1000) - 3600, // 1 hour ago
  end: Math.floor(Date.now() / 1000),
});
​
zone_id
string
required
Zone identifier
​
start
number
Start timestamp (Unix timestamp in seconds)
​
end
number
End timestamp (Unix timestamp in seconds)
​
fields
string
Comma-separated list of fields to include (e.g., ClientIP,EdgeStartTimestamp,RayID)
​
sample
number
Sampling rate (0.01 = 1% of logs)
​
timestamps
'unix' | 'unixnano' | 'rfc3339'
Timestamp format
​
logs
array
Array of log entries matching the query
Received logs provide detailed information about HTTP requests processed by Cloudflare, including client information, request/response details, performance metrics, and security events.

​
Control

Manage log retention and control settings. 
const control = client.logs.control;
The control resource provides methods for managing log retention policies and access controls.

​
Use cases

The Logs API is useful for:
  • Debugging: Look up specific requests using Ray IDs
  • Analytics: Analyze traffic patterns and performance metrics
  • Security: Investigate suspicious requests and attacks
  • Compliance: Export logs for audit and compliance requirements
  • Monitoring: Build custom dashboards and alerting systems

​
Available log fields

Common fields available in request logs:
  • ClientIP - Client IP address
  • ClientRequestHost - Host header from the request
  • ClientRequestMethod - HTTP method (GET, POST, etc.)
  • ClientRequestURI - Request URI
  • EdgeStartTimestamp - Unix nanosecond timestamp
  • EdgeEndTimestamp - Unix nanosecond timestamp
  • RayID - Unique request identifier
  • EdgeResponseStatus - HTTP status code
  • CacheResponseStatus - Cache status (hit, miss, etc.)
  • SecurityLevel - Security level applied
  • WAFAction - WAF action taken
  • WAFFlags - WAF rule flags
  • WAFMatchedVar - WAF matched variable
See the Cloudflare documentation for a complete list of available fields.

Build docs developers (and LLMs) love

Get started for freeTalk to us