--- updatedAt: 2026-09-16T12:15:40.000Z agentTools: projectIndex: https://docs.hud.io/llms.txt --- # List issues Retrieve a paginated list of issues detected by Hud. **Filtering Options:** - Filter by environment (default: production) - Filter by service ID(s) or service name(s) - Filter by time range (relative like "7d" or explicit ISO 8601 timestamps) - Filter by custom tags **Response:** Returns an array of issues with pagination metadata. Each issue includes: - Issue details (id, type, title, summary) - Timing information (first_seen_at, last_seen_at) - Affected entity details (endpoint, queue, or function) - Source function **Example:** `GET /issues?relative_time_frame=7d&service_name=payment-service&limit=10` # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "HUD Public API", "description": "Public API for accessing HUD issues and metrics", "version": "1.0.0" }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key for authentication (validated by API Gateway)" } } }, "paths": { "/v1/issues": { "get": { "operationId": "listIssues", "summary": "List issues", "tags": [ "Issues" ], "description": "Retrieve a paginated list of issues detected by Hud.\n\n**Filtering Options:**\n- Filter by environment (default: production)\n- Filter by service ID(s) or service name(s)\n- Filter by time range (relative like \"7d\" or explicit ISO 8601 timestamps)\n- Filter by custom tags\n\n**Response:**\nReturns an array of issues with pagination metadata. Each issue includes:\n- Issue details (id, type, title, summary)\n- Timing information (first_seen_at, last_seen_at)\n- Affected entity details (endpoint, queue, or function)\n- Source function\n\n**Example:**\n`GET /issues?relative_time_frame=7d&service_name=payment-service&limit=10`", "parameters": [ { "schema": { "default": "production", "type": "string" }, "in": "query", "name": "environment", "required": false, "description": "Filter issues by deployment environment (e.g., production, staging). Defaults to \"production\"" }, { "schema": { "anyOf": [ { "type": "number" }, { "type": "array", "items": { "type": "number" } } ] }, "in": "query", "name": "service_id", "required": false, "description": "Filter by service ID(s). Accepts single value or array. Cannot be used together with service_name" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "in": "query", "name": "service_name", "required": false, "description": "Filter by service name(s). Accepts single value or array. Cannot be used together with service_id" }, { "schema": { "default": "7d", "type": "string", "enum": [ "1h", "1d", "7d", "14d", "30d", "60d" ] }, "in": "query", "name": "relative_time_frame", "required": false, "description": "Relative time window for filtering issues. Options: 1h (last hour), 1d (last day), 7d (last week), 14d (last 2 weeks), 30d (last month), 60d (last 2 months). Defaults to \"7d\". Cannot be used with explicit_time_frame_start/end" }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "in": "query", "name": "explicit_time_frame_start", "required": false, "description": "Start of explicit time range in ISO 8601 format (e.g., \"2024-01-15T00:00:00Z\"). Must be used together with explicit_time_frame_end. Cannot be used with relative_time_frame" }, { "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "in": "query", "name": "explicit_time_frame_end", "required": false, "description": "End of explicit time range in ISO 8601 format (e.g., \"2024-01-22T23:59:59Z\"). Must be used together with explicit_time_frame_start. Cannot be used with relative_time_frame" }, { "schema": { "default": 50, "type": "number", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of issues to return per page. Range: 1-100. Defaults to 50" }, { "schema": { "default": 0, "type": "number", "minimum": 0 }, "in": "query", "name": "offset", "required": false, "description": "Number of issues to skip for pagination. Defaults to 0" }, { "schema": { "default": "last_seen_at", "type": "string", "enum": [ "detected_at", "first_seen_at", "last_seen_at" ] }, "in": "query", "name": "sort_by", "required": false, "description": "Field to sort results by. Options: detected_at, first_seen_at, last_seen_at. Defaults to \"last_seen_at\"" }, { "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] }, "in": "query", "name": "sort_order", "required": false, "description": "Sort direction. Options: asc (oldest first), desc (newest first). Defaults to \"desc\"" }, { "schema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "in": "query", "name": "tags", "required": false, "description": "Filter by custom tags as key-value pairs. Example: {\"customer_id\": \"acme\", \"region\": [\"us-east\", \"eu-west\"]}" } ], "responses": { "200": { "description": "Paginated list of production issues", "content": { "application/json": { "schema": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique identifier for the issue" }, "url": { "type": "string", "description": "Direct link to view this issue in the Hud dashboard" }, "type": { "type": "string", "enum": [ "postdeploy_error", "postdeploy_degradation", "error", "degradation", "slo_breach", "bad_request" ], "description": "Issue classification type: postdeploy_error (new error after deployment), postdeploy_degradation (performance regression after deployment), error (runtime exception), degradation (performance issue), slo_breach (SLO violation), bad_request (client error)" }, "first_seen_at": { "type": "string", "description": "ISO 8601 timestamp when this issue was first detected" }, "last_seen_at": { "type": "string", "description": "ISO 8601 timestamp of the most recent occurrence" }, "title": { "type": "string", "description": "Human-readable title summarizing the issue" }, "summary": { "description": "AI-generated summary explaining the issue context and potential impact", "type": "string" }, "service_id": { "type": "number", "description": "Unique identifier of the affected service" }, "service_name": { "type": "string", "description": "Name of the affected service" }, "environment": { "description": "Deployment environment where the issue occurred (e.g., production, staging)", "type": "string" }, "affected_entity": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "endpoint", "queue", "function" ], "description": "Type of the affected entity" }, "id": { "type": "string", "description": "Unique identifier for the affected entity" }, "signature": { "type": "string", "description": "Method signature or route pattern of the affected entity" }, "url": { "type": "string", "description": "Direct link to view this entity in the Hud dashboard" } }, "required": [ "type", "id", "signature", "url" ], "additionalProperties": false, "description": "The specific endpoint, queue, or function where the issue manifests" }, "specific_tag": { "description": "Specific tag that distinguishes this issue variant (e.g., specific error code or customer segment)", "type": "object", "properties": { "key": { "type": "string", "description": "Tag key name" }, "value": { "type": "string", "description": "Tag value" } }, "required": [ "key", "value" ], "additionalProperties": false }, "source_functions": { "description": "List of functions in the call stack where the issue originates", "type": "array", "items": { "type": "object", "properties": { "function": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the function" }, "signature": { "type": "string", "description": "Full function signature including class and method name" }, "url": { "type": "string", "description": "Direct link to view this function in the HUD dashboard" } }, "required": [ "id", "signature", "url" ], "additionalProperties": false }, "failure_type": { "description": "Type of failure (e.g., exception, timeout)", "type": "string" }, "exception_type": { "description": "Fully qualified exception class name if applicable", "type": "string" } }, "required": [ "function" ], "additionalProperties": false } } }, "required": [ "id", "url", "type", "first_seen_at", "last_seen_at", "title", "service_id", "service_name", "affected_entity" ], "additionalProperties": false, "description": "A production issue detected by HUD, representing an error, degradation, or anomaly in your application" }, "description": "Array of issues matching the query filters" }, "total": { "type": "number", "description": "Total number of issues matching the filters (before pagination)" }, "limit": { "type": "number", "description": "Maximum number of issues returned per page" }, "offset": { "type": "number", "description": "Number of issues skipped for pagination" } }, "required": [ "issues", "total", "limit", "offset" ], "additionalProperties": false, "description": "Paginated list of production issues" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "error" ], "additionalProperties": false, "description": "Unauthorized" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "error" ], "additionalProperties": false, "description": "Forbidden" } } } }, "500": { "description": "InternalServerError", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing what went wrong" } }, "required": [ "error" ], "additionalProperties": false, "description": "InternalServerError" } } } } } } } }, "servers": [ { "url": "https://api.hud.io", "description": "Production server" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Issues", "description": "Endpoints for retrieving and managing production issues detected by Hud" } ] } ```