Skip to main content

​
Endpoint

GET /logs/api/entries
Retrieves historical webhook log entries with memory-efficient streaming, filtering, and pagination.
Security Warning: This endpoint is NOT protected by authentication. Never expose it outside your trusted network. Deploy behind a reverse proxy with authentication, use firewall rules to restrict access, and never expose log viewer ports directly to the internet. Log files may contain GitHub tokens, user information, repository details, and sensitive webhook payloads.

​
Query Parameters

All query parameters are optional. Use them to filter and paginate results.
​
hook_id
string
Filter by specific GitHub delivery ID (x-github-delivery header value)Example: hook_id=abc123-def456
​
pr_number
integer
Filter by pull request numberExample: pr_number=123
​
repository
string
Filter by repository name in owner/repo formatExample: repository=my-org/my-repo
​
event_type
string
Filter by GitHub event type (e.g., pull_request, check_run, push)Example: event_type=pull_request
​
github_user
string
Filter by GitHub username (api_user field)Example: github_user=octocat
​
level
string
Filter by log levelAllowed values: DEBUG, INFO, WARNING, ERRORExample: level=ERROR
​
start_time
string
Start time filter in ISO 8601 formatExample: start_time=2025-01-30T10:00:00Z
​
end_time
string
End time filter in ISO 8601 formatExample: end_time=2025-01-30T12:00:00Z
​
search
string
Full-text search in log messages (case-insensitive)Example: search=signature%20verification
​
limit
integer
default:"100"
Maximum number of entries to return (1-10,000)Example: limit=50
​
offset
integer
default:"0"
Pagination offset (number of entries to skip)Example: offset=100

​
Response

​
entries
array
Array of log entry objects matching the applied filters
​
entries_processed
integer | string
Number of log entries examined during this request. May be an integer or string with ”+” suffix (e.g., "50000+") indicating the streaming process reached its maximum processing limit and more entries exist.
​
filtered_count_min
integer
Minimum number of entries matching the current filters. Calculated as len(entries) + offset, representing the definitive lower bound of matching entries. Useful for pagination calculations and showing “showing X of at least Y results” messages.
​
total_log_count_estimate
string
Statistical estimate of total log entries across all log files (including rotated logs). Provides context about overall dataset size for UI statistics and capacity planning. Based on sampling the first 10 log files to balance accuracy with performance.Examples: "1.2M", "45.3K", "892"
​
limit
integer
Echo of the requested limit parameter
​
offset
integer
Echo of the requested offset parameter
​
is_partial_scan
boolean
Indicates whether the streaming process examined all available logs (false) or stopped at the processing limit (true)

​
Examples

​
Get recent errors for a specific PR

curl "http://localhost:5000/logs/api/entries?pr_number=123&level=ERROR&limit=50"

{
  "entries": [
    {
      "timestamp": "2025-01-30T10:30:00.123000",
      "level": "ERROR",
      "logger_name": "PullRequestHandler",
      "message": "Failed to assign reviewers: API rate limit exceeded",
      "hook_id": "abc123-def456",
      "event_type": "pull_request",
      "repository": "my-org/my-repo",
      "pr_number": 123,
      "github_user": "octocat"
    }
  ],
  "entries_processed": 1500,
  "filtered_count_min": 1,
  "total_log_count_estimate": "45.3K",
  "limit": 50,
  "offset": 0,
  "is_partial_scan": false
}

​
Search for specific text in logs

curl "http://localhost:5000/logs/api/entries?search=signature%20verification&limit=25"

​
Filter by repository and time range

curl "http://localhost:5000/logs/api/entries?repository=my-org/my-repo&start_time=2025-01-30T00:00:00Z&end_time=2025-01-30T23:59:59Z&limit=100"

​
Pagination example

# Get first page
curl "http://localhost:5000/logs/api/entries?limit=100&offset=0"

# Get second page
curl "http://localhost:5000/logs/api/entries?limit=100&offset=100"

# Get third page
curl "http://localhost:5000/logs/api/entries?limit=100&offset=200"

​
Track specific webhook delivery

curl "http://localhost:5000/logs/api/entries?hook_id=abc123-def456"

​
Performance Notes

  • Memory-efficient streaming: Handles log files of any size with constant memory footprint
  • Early filtering: Applies filters during parsing to reduce memory usage
  • Sub-second responses: Optimized for fast queries even with large datasets
  • Processing limits:
    • Without filters: processes up to 20,000 entries
    • With filters: processes up to 50,000 entries
    • Maximum 25 most recent log files examined

​
Error Responses

​
400 Bad Request
error
Invalid parameters (e.g., limit out of range, negative offset)
{
  "detail": "Limit must be between 1 and 10000"
}
​
500 Internal Server Error
error
File access errors or internal server errors
{
  "detail": "Error accessing log files"
}

​
Use Cases

  • Debugging: Find error logs for specific PRs or webhooks
  • Monitoring: Track webhook processing for repositories
  • Analysis: Search for specific events or patterns
  • Auditing: Review historical webhook activity
  • Troubleshooting: Investigate failures by filtering on error levels

Build docs developers (and LLMs) love

Get started for freeTalk to us