> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API Request Logs
> View detailed API request history with filtering by status code, method, route, client, latency, and more. Export logs to CSV for analysis.
# 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
1. Click **Logs** in the sidebar
2. Select **API Logs**
3. See recent requests (most recent first)
### Step 2: Use Filters
**Filter by Status Code:**
```text theme={"dark"}
☐ 2xx Success
☐ 3xx Redirect
☐ 4xx Client Error
☐ 5xx Server Error
```
**Filter by HTTP Method:**
```text theme={"dark"}
☐ 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:**
```text theme={"dark"}
☐ 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:**
```text theme={"dark"}
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:**
```text theme={"dark"}
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:**
```text theme={"dark"}
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:**
```text theme={"dark"}
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:**
1. Filter by Status: 5xx Server Error
2. Filter by Route: stripe-payments
3. Filter by Time: Last hour
4. Find user's request
5. View error details
6. Identify issue (e.g., Stripe API down)
### Use Case 2: Investigating Slow Requests
**Scenario:** Users complaining about slow checkout
**Steps:**
1. Filter by Route: checkout-route
2. Filter by Latency: Min 2000ms (>2 seconds)
3. Sort by latency (highest first)
4. View slowest requests
5. Check common patterns (specific endpoint? time of day?)
6. Optimize accordingly
### Use Case 3: Security Audit
**Scenario:** Suspicious activity detected
**Steps:**
1. Filter by Status: 401 Unauthorized OR 403 Forbidden
2. Review source IPs
3. Identify unauthorized access attempts
4. Block malicious IPs
5. Export logs for security review
### Use Case 4: Client Verification
**Scenario:** Client reports requests not reaching backend
**Steps:**
1. Filter by Client: client-name
2. Filter by Time: Expected time window
3. Check if requests appear
4. If yes: Check status codes, errors
5. If no: Client not sending to correct URL/route
### Use Case 5: Secret Usage Audit
**Scenario:** Which routes use a specific secret?
**Steps:**
1. Navigate to Secret detail page
2. Click "View Logs" or "Usage"
3. See all requests that injected this secret
4. Verify expected routes only
## Advanced Filtering
### Combining Filters
**Example: High-latency errors**
```text theme={"dark"}
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:**
```text theme={"dark"}
/api/users
```
**Search by error:**
```text theme={"dark"}
timeout
connection refused
```
**Search by query parameter:**
```text theme={"dark"}
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:**
1. Apply filters to select logs
2. Click **Export** button
3. CSV downloads automatically
**File name format:**
```text theme={"dark"}
api-logs-{tenant-slug}-{timestamp}.csv
```
**Example:**
```text theme={"dark"}
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:**
```text theme={"dark"}
2025-01-15 10:30:45 EST
```
**Includes:**
* Date
* Time (24-hour format)
* Timezone abbreviation
## Troubleshooting
### Issue: "No logs displayed"
**Causes:**
* No requests in time range
* Filters too restrictive
* Logs expired (past retention period)
**Fix:**
1. Clear all filters
2. Expand time range
3. 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:**
1. Navigate to Settings → Profile
2. Update timezone
3. 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:**
1. Alert fires (e.g., high error rate)
2. Click "View Logs" from alert
3. See filtered logs that triggered alert
4. 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
## Related Features
* **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
Configure alerts from log patterns
View aggregate metrics
Track configuration changes
Configure routes to monitor
***
* **Level**: beginner
* **Time**: 10 minutes
`logs`, `monitoring`, `debugging`, `audit`, `export`