API Request Logs

View detailed history of every API request proxied through KnoxCall with powerful filtering and export capabilities.

Overview

API Logs provide complete visibility into your API traffic:

📋 Every request logged with full details
🔍 Filter by status, method, route, client, latency
📊 Search request paths and errors
💾 Export to CSV (Pro/Enterprise plans)
🔗 Deep links from alerts and analytics
⏰ Timezone-aware timestamps

Retention: Based on subscription plan (7-90 days)

Log Entry Details

Each log entry captures:

Request Information

Timestamp: When request received (your timezone)
Method: HTTP method (GET, POST, PUT, DELETE, etc.)
Path: Request path including query parameters
Route: Which KnoxCall route handled it
Environment: Environment used (if specified)

Client Information

Client: Client name/IP that made request
Source IP: Originating IP address
User Agent: Client’s user agent string
Geographic Location: City, country (if available)

Response Information

Status Code: HTTP response code (200, 404, 500, etc.)
Latency: Response time in milliseconds
Backend Response: Status from target API
Error: Error message if request failed

Security Information

API Key: Which key authenticated request (key ID only, not full key)
Authorization: Whether authorized (client IP whitelisted)
Secrets Used: Which secrets injected (names only, not values)

Viewing Logs

Step 1: Navigate to Logs

Click Logs in the sidebar
Select API Logs
See recent requests (most recent first)

Step 2: Use Filters

Filter by Status Code:

☐ 2xx Success
☐ 3xx Redirect
☐ 4xx Client Error
☐ 5xx Server Error

Filter by HTTP Method:

☐ GET
☐ POST
☐ PUT
☐ DELETE
☐ PATCH

Filter by Route: Select specific route from dropdown Filter by Client: Select specific client from dropdown Filter by Secret: Show requests that used specific secret Filter by Proxy Mode:

☐ Route (standard proxied routes)
☐ Ephemeral (one-shot ephemeral proxy sessions)

Use Ephemeral to isolate one-shot ephemeral proxy requests from your standard route traffic — useful when debugging ad-hoc agent calls or testing ephemeral sessions without cluttering your route log. Filter by Latency:

Min: ___ ms
Max: ___ ms

Search: Search request paths, errors, or any text

Step 3: View Log Details

Click any log entry to see full details: Request tab:

Method: POST
Path: /v1/charges?amount=1000
Headers:
  Content-Type: application/json
  x-knoxcall-key: tk_abc***
  x-knoxcall-route: stripe-payments
  x-knoxcall-environment: production
Body:
{
  "amount": 1000,
  "currency": "usd",
  "source": "tok_visa"
}

Response tab:

Status: 200 OK
Latency: 234ms
Headers:
  Content-Type: application/json
  X-Request-ID: req_xyz789
Body:
{
  "id": "ch_abc123",
  "amount": 1000,
  "status": "succeeded"
}

Metadata tab:

Route: stripe-payments
Environment: production
Client: production-server-01 (52.123.45.67)
API Key: key_abc123... (Production Key)
Secrets Used:
  - stripe-prod-key (injected in Authorization header)
Timestamp: 2025-01-15 10:30:45 EST
Geographic: New York, USA → Virginia, USA

Common Use Cases

Use Case 1: Debugging Failed Requests

Scenario: User reports payment failed Steps:

Filter by Status: 5xx Server Error
Filter by Route: stripe-payments
Filter by Time: Last hour
Find user’s request
View error details
Identify issue (e.g., Stripe API down)

Use Case 2: Investigating Slow Requests

Scenario: Users complaining about slow checkout Steps:

Filter by Route: checkout-route
Filter by Latency: Min 2000ms (>2 seconds)
Sort by latency (highest first)
View slowest requests
Check common patterns (specific endpoint? time of day?)
Optimize accordingly

Use Case 3: Security Audit

Scenario: Suspicious activity detected Steps:

Filter by Status: 401 Unauthorized OR 403 Forbidden
Review source IPs
Identify unauthorized access attempts
Block malicious IPs
Export logs for security review

Use Case 4: Client Verification

Scenario: Client reports requests not reaching backend Steps:

Filter by Client: client-name
Filter by Time: Expected time window
Check if requests appear
If yes: Check status codes, errors
If no: Client not sending to correct URL/route

Use Case 5: Secret Usage Audit

Scenario: Which routes use a specific secret? Steps:

Navigate to Secret detail page
Click “View Logs” or “Usage”
See all requests that injected this secret
Verify expected routes only

Advanced Filtering

Combining Filters

Example: High-latency errors

Status: 5xx Server Error
Latency: Min 1000ms
Route: stripe-payments
Time: Last 24 hours

Result: Slow requests that also errored (likely timeouts)

Search Operators

Search by path:

/api/users

Search by error:

timeout
connection refused

Search by query parameter:

user_id=12345

Exporting Logs

CSV Export (Pro/Enterprise Only)

What’s exported:

Timestamp
Method
Path
Status Code
Client name
Source IP
Latency (ms)
Error message (if any)

Steps:

Apply filters to select logs
Click Export button
CSV downloads automatically

File name format:

api-logs-{tenant-slug}-{timestamp}.csv

Example:

api-logs-DunderMifflin-1705326645000.csv

Use Cases for Export

Compliance audits:

Export last 90 days
Provide to auditors
Demonstrate API usage

Custom analysis:

Import to Excel/Google Sheets
Create pivot tables
Generate custom reports

Archiving:

Export monthly logs
Store in secure location
Maintain historical record beyond retention period

Pagination

Logs per page: 10 (configurable) Navigation:

Next/Previous buttons
Jump to page dropdown
Total count displayed

Performance:

Indexed queries (fast even with millions of logs)
Lazy loading (only fetch current page)

Retention Policies

By subscription plan:

Plan	Retention Period
Starter	7 days
Pro	30 days
Enterprise	90 days (customizable)

After retention:

Logs automatically deleted
Export before expiration if needed
Upgrade plan for longer retention

Deep Links

Jump to logs from: Alerts:

Alert triggers → View triggering requests

Analytics:

Click chart → Drill down to specific time period

Route Details:

View logs for specific route

Client Details:

View logs from specific client

Secret Details:

View requests using secret

Timezone Handling

Timestamps displayed in:

Your configured timezone (Settings → Profile)
Default: UTC

Format:

2025-01-15 10:30:45 EST

Includes:

Date
Time (24-hour format)
Timezone abbreviation

Who can see captured payloads

A request log’s detail is metadata for everyone: status, timing, path, egress, client and injection summary. Its captured headers and bodies, and the archived request and response bodies, are withheld until you click Reveal payload (the API equivalent is GET /admin/logs/{request_id}?include=payload). Downloading or previewing an archived body is a reveal of its own: the Download and Preview buttons appear on the page as soon as it opens, so you do not have to reveal the inline headers and bodies first. In the dashboard this is a Class B reveal: only an Owner or an Admin can do it (an Editor cannot, even with Reveal secrets turned on; that setting covers secret values, certificates and credentialed workflow tests only), and every use asks for a fresh second factor (an authenticator code, a passkey or a security key; an emailed code does not count). Each use writes a plaintext.reveal entry to the audit log before anything is shown, and counts against the same per-person reveal budget as showing a secret’s value (60 per 5 minutes). If the audit entry cannot be written, or the budget cannot be counted, the request is refused rather than served. The Management API’s request logs (/v1/logs) return metadata only and never a captured payload. A tenant policy that denies log:read_payload still refuses (with "code": "reveal_policy_denied") before your verification is spent.

Troubleshooting

Issue: “No logs displayed”

Causes:

No requests in time range
Filters too restrictive
Logs expired (past retention period)

Fix:

Clear all filters
Expand time range
Check if route is active

Issue: “Can’t export logs”

Cause: Starter plan (export requires Pro/Enterprise) Fix: Upgrade subscription plan

Issue: “Missing request details”

Cause: Log entry truncated (very large request/response) Details stored:

Headers: All
Body: First 10KB
Response: First 10KB

If truncated: See “(truncated)” indicator

Issue: “Logs show wrong timezone”

Fix:

Navigate to Settings → Profile
Update timezone
Logs update automatically

Best Practices

1. Regular Log Reviews

Weekly:

Review error logs (4xx, 5xx)
Identify patterns
Fix recurring issues

2. Export for Long-Term Storage

Monthly:

Export last 30 days
Archive to secure storage
Maintain audit trail

3. Use Filters to Reduce Noise

Focus on what matters:

Filter out successful requests (when debugging)
Filter specific routes (when investigating)
Use latency filters (performance analysis)

4. Combine with Alerts

Workflow:

Alert fires (e.g., high error rate)
Click “View Logs” from alert
See filtered logs that triggered alert
Investigate root cause

5. Monitor Unauthorized Attempts

Security practice:

Weekly review of 401/403 errors
Identify patterns (IP ranges, times)
Block malicious actors
Alert on unusual activity

Alerts: Set up alerts based on log patterns
Analytics: Aggregate log data into metrics
Audit Logs: Track configuration changes (separate from API logs)

Next Steps

Alerts

Configure alerts from log patterns

Analytics

View aggregate metrics

Audit Logs

Track configuration changes

Routes

Configure routes to monitor

📊 Statistics

Level: beginner
Time: 10 minutes

🏷️ Tags

logs, monitoring, debugging, audit, export

​API Request Logs

​Overview

​Log Entry Details

​Request Information

​Client Information

​Response Information

​Security Information

​Viewing Logs

​Step 1: Navigate to Logs

​Step 2: Use Filters

​Step 3: View Log Details

​Common Use Cases

​Use Case 1: Debugging Failed Requests

​Use Case 2: Investigating Slow Requests

​Use Case 3: Security Audit

​Use Case 4: Client Verification

​Use Case 5: Secret Usage Audit

​Advanced Filtering

​Combining Filters

​Search Operators

​Exporting Logs

​CSV Export (Pro/Enterprise Only)

​Use Cases for Export

​Pagination

​Retention Policies

​Deep Links

​Timezone Handling

​Who can see captured payloads

​Troubleshooting

​Issue: “No logs displayed”

​Issue: “Can’t export logs”

​Issue: “Missing request details”

​Issue: “Logs show wrong timezone”

​Best Practices

​1. Regular Log Reviews

​2. Export for Long-Term Storage

​3. Use Filters to Reduce Noise

​4. Combine with Alerts

​5. Monitor Unauthorized Attempts

​Related Features

​Next Steps