> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blocklight.co/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /api/v1/detections

> List recent detections with optional filters

List recent detections with optional query parameters for filtering.

## Endpoint

```
GET /api/v1/detections
```

## Query Parameters

| Parameter  | Type   | Description                                    | Default |
| ---------- | ------ | ---------------------------------------------- | ------- |
| `limit`    | number | Number of results                              | 50      |
| `offset`   | number | Pagination offset                              | 0       |
| `severity` | string | Filter by priority (NOTICE, WARNING, CRITICAL) | -       |
| `chain`    | string | Filter by blockchain (ethereum, polygon, etc.) | -       |
| `rule`     | string | Filter by rule name                            | -       |

## Example Requests

```bash theme={null}
# Recent detections
curl "http://localhost:8000/api/v1/detections?limit=10"

# Critical findings only
curl "http://localhost:8000/api/v1/detections?severity=CRITICAL"

# Ethereum detections
curl "http://localhost:8000/api/v1/detections?chain=ethereum&limit=20"
```

## Response

```json theme={null}
{
  "count": 10,
  "detections": [
    {
      "id": "finding_abc123",
      "rule_name": "flash_loan_attack",
      "detector_name": "flash_loan_attack",
      "severity": "CRITICAL",
      "priority": "CRITICAL",
      "chain": "ethereum",
      "type": "rule",
      "tx_hash": "0x9e5c7835...",
      "block_number": 18450123,
      "timestamp": "2025-11-11T21:30:00Z",
      "description": "Flash loan attack detected: 1000 ETH borrowed",
      "tags": ["defi", "flash-loan"],
      "metadata": {
        "tx_from": "0x742d...",
        "tx_to": "0x123f...",
        "tx_value": "1000000000000000000"
      }
    },
    ...
  ]
}
```

## Response Fields

| Field                        | Type   | Description                                |
| ---------------------------- | ------ | ------------------------------------------ |
| `count`                      | number | Number of detections returned              |
| `detections`                 | array  | Array of detection objects                 |
| `detections[].id`            | string | Unique detection ID                        |
| `detections[].rule_name`     | string | Name of the rule that triggered            |
| `detections[].detector_name` | string | Detector name (same as rule\_name)         |
| `detections[].severity`      | string | Severity level (NOTICE, WARNING, CRITICAL) |
| `detections[].priority`      | string | Priority level (same as severity)          |
| `detections[].chain`         | string | Blockchain network                         |
| `detections[].type`          | string | Detection type (usually "rule")            |
| `detections[].tx_hash`       | string | Transaction hash                           |
| `detections[].block_number`  | number | Block number                               |
| `detections[].timestamp`     | string | Detection timestamp (ISO 8601)             |
| `detections[].description`   | string | Alert message/description                  |
| `detections[].tags`          | array  | Rule tags                                  |
| `detections[].metadata`      | object | Additional transaction metadata            |

<Note>
  **Pagination:** Use `limit` and `offset` for large result sets. Maximum `limit` is 1000.
</Note>