|---|---|---|
| limit | integer | No | 20 | 5, 10, 20, 30, 50 | Maximum number of historical run records to return. |
The limit parameter controls the size of the returned dataset. The implementation enforces a strict allowlist of values. If an unlisted value is provided (e.g., limit=15 or limit=100), the server silently coerces it to the default value of 20. This design prevents unbounded queries while maintaining predictable response payloads and reducing database load.
Example Request
GET /api/local-only/run-history?limit=10 HTTP/1.1
Host: localhost:3000
Accept: application/json
All responses return a JSON payload with a consistent structure. The ok field indicates success, while error provides diagnostic information when the request fails.
Success Response (200 OK)
{
"ok": true,
"limit": 10,
"rows": [
{
"run_id": "run_8f3a2c1d",
"timestamp": "2024-05-12T14:32:00Z",
"status": "completed",
"duration_ms": 1240,
"pages_crawled": 84,
"errors": 0
},
{
"run_id": "run_7b9e4f2a",
"timestamp": "2024-05-12T13:15:00Z",
"status": "failed",
"duration_ms": 450,
"pages_crawled": 12,
"errors": 3
}
]
}
The rows array contains execution records ordered by recency. Each object includes metadata such as run identifiers, execution timestamps, status codes, performance metrics, and error counts. The exact shape of rows is determined by the underlying readCrawlerRunHistory utility, which abstracts the storage layer. The limit field in the response confirms the effective limit applied, allowing clients to verify coercion behavior.
Error Responses
| Status Code | Condition | Response Body |
|---|
404 Not Found | Local Crawler UI is disabled in environment configuration | {"ok": false, "error": "Not found"} |
500 Internal Server Error | Underlying storage or utility failure (not explicitly handled in route) | Standard Next.js error payload |
The 404 response is intentional. The route uses assertLocalCrawlerUiEnabled() to verify that the local crawler interface is active. If the environment variable or configuration flag is missing or set to false, the guard throws an exception, which the route catches and maps to a 404. This prevents accidental exposure of internal execution data in restricted or production environments.
Usage Example
Retrieve the 30 most recent crawler runs:
curl -X GET "http://localhost:3000/api/local-only/run-history?limit=30" \
-H "Accept: application/json"
Retrieve runs using the default limit (20):
curl -X GET "http://localhost:3000/api/local-only/run-history"
Test invalid limit coercion:
curl -X GET "http://localhost:3000/api/local-only/run-history?limit=99"
# Returns limit: 20 in the response body
Common Pitfalls
- Silent Limit Coercion: The endpoint does not return a
400 Bad Request for invalid limit values. Instead, it falls back to 20. Developers building strict validation layers should explicitly check the limit field in the response or pre-validate against the allowlist [5, 10, 20, 30, 50] before making requests to avoid unexpected pagination behavior.
- Environment Guard Returns 404: A
404 response does not necessarily mean the route is misconfigured or missing. It indicates that the local crawler UI feature flag is disabled. Verify that the appropriate environment variable is set to true in your .env file. This guard is deliberately strict to prevent local debugging tools from leaking into production deployments.
- Caching Misconceptions: Despite being a
GET request, the route is explicitly marked as force-dynamic. Standard HTTP caching headers are not applied, and Next.js will not serve stale responses from the edge or build cache. This is intentional for real-time debugging but can increase server load if polled aggressively. Implement client-side debouncing or interval throttling when integrating with UI dashboards or automated monitoring scripts.
This endpoint is part of the local crawler management suite and is typically used alongside complementary routes that handle execution control and configuration:
- Run Execution: Endpoints that trigger new crawler jobs often return a
run_id that can be cross-referenced with the history data returned here. Developers use this relationship to track job lifecycle from initiation to completion.
- Configuration Management: Routes that expose or modify crawler settings (e.g., target URLs, concurrency limits, or exclusion rules) share the same environment guard. Disabling the UI flag affects all local-only management routes simultaneously, ensuring consistent security boundaries.
- Real-Time Status Polling: While this endpoint provides historical snapshots, adjacent endpoints may offer WebSocket or Server-Sent Event (SSE) streams for live run progress. Developers typically use
/api/local-only/run-history for post-execution analysis and the streaming endpoints for active monitoring.
When building automation scripts or internal tooling, ensure that all local-only routes are called within the same environment context. Mixing authenticated production endpoints with local-only routes can lead to configuration mismatches or unexpected 404 responses due to feature flag boundaries. Always verify environment variables before deploying scripts that depend on this route.
