prowler/docs/api-reference/findings/list.mdx

---
title: "List Findings"
api: "GET /api/v1/findings"
description: "Retrieve a list of all findings with options for filtering by various criteria."
---

Retrieve security findings (vulnerabilities, misconfigurations, compliance violations) across your cloud infrastructure. This is one of the most frequently used endpoints for analyzing your security posture.

## Use Cases

- **Security Dashboard**: Display current security findings and trends
- **Compliance Reporting**: Filter findings by compliance framework
- **Vulnerability Management**: Track and remediate security issues
- **Alerting & Notifications**: Query new or critical findings for alerts
- **Risk Assessment**: Analyze findings by severity and service
- **Audit Trails**: Export findings for compliance audits

## Query Parameters

### Required Filters

- `filter[inserted_at]` - At least one variation of this filter is required
- `filter[inserted_at__gte]` - Filter by creation date (greater than or equal). Maximum date range is 7 days
- `filter[inserted_at__lte]` - Filter by creation date (less than or equal). Maximum date range is 7 days

### Filtering Options

**By Check:**
- `filter[check_id]`, `filter[check_id__icontains]`, `filter[check_id__in]` - Filter by check ID

**By Status:**
- `filter[status]` - Filter by status: `FAIL`, `PASS`, `MANUAL`
- `filter[severity]` - Filter by severity: `critical`, `high`, `medium`, `low`, `informational`
- `filter[delta]` - Filter by change status: `new`, `changed`
- `filter[muted]` - Filter by mute status (boolean)

**By Provider:**
- `filter[provider]`, `filter[provider__in]` - Filter by provider UUID
- `filter[provider_type]`, `filter[provider_type__in]` - Filter by provider type: `aws`, `azure`, `gcp`, `kubernetes`, `m365`, `github`, `oci`
- `filter[provider_alias]`, `filter[provider_alias__icontains]` - Filter by provider alias
- `filter[provider_uid]`, `filter[provider_uid__icontains]` - Filter by provider UID

**By Resource:**
- `filter[resource_name]`, `filter[resource_name__icontains]` - Filter by resource name
- `filter[resource_type]`, `filter[resource_type__icontains]` - Filter by resource type
- `filter[resource_uid]`, `filter[resource_uid__icontains]` - Filter by resource UID
- `filter[region]`, `filter[region__icontains]`, `filter[region__in]` - Filter by region
- `filter[service]`, `filter[service__icontains]` - Filter by cloud service

**By Scan:**
- `filter[scan]`, `filter[scan__in]` - Filter by scan UUID

### Pagination

- `page[number]` - Page number to retrieve
- `page[size]` - Number of results per page

### Sorting

- `sort` - Field to sort by: `status`, `-status`, `severity`, `-severity`, `check_id`, `-check_id`, `inserted_at`, `-inserted_at`, `updated_at`, `-updated_at`

### Field Selection

- `fields[findings]` - Specify which fields to return

### Include Related Resources

- `include` - Include related resources: `scan`, `resources`

## Example Request

```bash
curl -X GET "https://api.prowler.com/api/v1/findings?filter[inserted_at__gte]=2024-01-01&filter[status]=FAIL&filter[severity]=high&page[size]=20" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/vnd.api+json"
```

## Response

### Success Response (200 OK)

Returns a paginated list of findings with full details:

```json
{
  "data": [
    {
      "type": "findings",
      "id": "finding-uuid",
      "attributes": {
        "uid": "prowler-aws-s3-bucket-unencrypted-123456",
        "check_id": "s3_bucket_default_encryption",
        "status": "FAIL",
        "status_extended": "S3 Bucket 'my-bucket' does not have default encryption enabled",
        "severity": "high",
        "muted": false,
        "muted_reason": null,
        "delta": "new",
        "inserted_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z",
        "first_seen_at": "2024-01-15T10:30:00Z",
        "check_metadata": {
          "Provider": "aws",
          "CheckID": "s3_bucket_default_encryption",
          "CheckTitle": "Check if S3 buckets have default encryption enabled",
          "CheckType": "Software and Configuration Checks",
          "ServiceName": "s3",
          "SubServiceName": "",
          "ResourceIdTemplate": "arn:partition:s3:::bucket_name",
          "Severity": "high",
          "ResourceType": "AwsS3Bucket",
          "Description": "S3 buckets should have encryption at rest enabled...",
          "Risk": "Unencrypted S3 buckets can expose sensitive data...",
          "RelatedUrl": "https://docs.aws.amazon.com/...",
          "Remediation": {
            "Code": {
              "CLI": "aws s3api put-bucket-encryption...",
              "NativeIaC": "...",
              "Other": "...",
              "Terraform": "..."
            },
            "Recommendation": {
              "Text": "Enable default encryption on S3 bucket",
              "Url": "https://docs.aws.amazon.com/..."
            }
          },
          "Categories": ["encryption"],
          "DependsOn": [],
          "RelatedTo": [],
          "Notes": ""
        },
        "raw_result": {
          "finding_unique_id": "...",
          "finding_uid": "...",
          "status": "FAIL",
          "status_extended": "...",
          "raw": {...}
        }
      },
      "relationships": {
        "scan": {
          "data": {
            "type": "scans",
            "id": "scan-uuid"
          }
        },
        "resources": {
          "data": [
            {
              "type": "resources",
              "id": "resource-uuid"
            }
          ]
        }
      }
    }
  ],
  "meta": {
    "page": {
      "number": 1,
      "size": 20,
      "total": 156,
      "total_pages": 8
    }
  },
  "links": {
    "self": "https://api.prowler.com/api/v1/findings?page[number]=1&page[size]=20",
    "first": "https://api.prowler.com/api/v1/findings?page[number]=1&page[size]=20",
    "next": "https://api.prowler.com/api/v1/findings?page[number]=2&page[size]=20",
    "last": "https://api.prowler.com/api/v1/findings?page[number]=8&page[size]=20"
  }
}
```

### Response Fields

**Core Finding Information:**
- `uid` (string, required) - Unique identifier for the finding (max 300 characters)
- `check_id` (string, required) - ID of the security check that generated this finding (max 100 characters)
- `status` (enum, required) - Finding status: `FAIL`, `PASS`, or `MANUAL`
- `status_extended` (string, nullable) - Detailed human-readable status message
- `severity` (enum, required) - Severity level: `critical`, `high`, `medium`, `low`, `informational`
- `delta` (enum, nullable) - Change status: `new`, `changed`, or `null`

**Mute Management:**
- `muted` (boolean) - Whether finding is muted (suppressed)
- `muted_reason` (string, nullable) - Reason for muting (3-500 characters)

**Timestamps:**
- `inserted_at` (datetime, read-only) - When finding was first created
- `updated_at` (datetime, read-only) - Last time finding was modified
- `first_seen_at` (datetime, nullable, read-only) - First time this finding was detected

**Check Details:**
- `check_metadata` (object) - Complete metadata about the security check including:
  - Title, description, risk assessment
  - Remediation steps and code examples
  - Related documentation URLs
  - Compliance frameworks and categories
- `raw_result` (object) - Complete raw output from the security check

**Relationships:**
- `scan` - Reference to the scan that generated this finding
- `resources` - References to affected cloud resources (read-only)

<Note>
Resource information (service, region, resource name, etc.) is available through the `resources` relationship. Use `include=resources` to fetch resource details along with findings.
</Note>

### Common Query Patterns

**Get all critical findings:**
```bash
curl "https://api.prowler.com/api/v1/findings?filter[severity]=critical&filter[status]=FAIL&filter[inserted_at__gte]=2024-01-01"
```

**Get new findings from last scan:**
```bash
curl "https://api.prowler.com/api/v1/findings/latest?filter[delta]=new&filter[status]=FAIL"
```

**Get findings for specific service:**
```bash
curl "https://api.prowler.com/api/v1/findings?filter[service]=s3&filter[inserted_at__gte]=2024-01-01"
```

**Get findings for specific region:**
```bash
curl "https://api.prowler.com/api/v1/findings?filter[region]=us-east-1&filter[inserted_at__gte]=2024-01-01"
```

**Get unmuted high/critical findings:**
```bash
curl "https://api.prowler.com/api/v1/findings?filter[severity__in]=critical,high&filter[muted]=false&filter[inserted_at__gte]=2024-01-01"
```

### Pagination

Use pagination parameters to navigate large result sets:

```bash
# First page, 50 results
curl "https://api.prowler.com/api/v1/findings?page[size]=50&page[number]=1&filter[inserted_at__gte]=2024-01-01"

# Next page
curl "https://api.prowler.com/api/v1/findings?page[size]=50&page[number]=2&filter[inserted_at__gte]=2024-01-01"
```

### Error Responses

**400 Bad Request** - Invalid filter or parameter
```json
{
  "errors": [
    {
      "status": "400",
      "title": "Invalid Filter",
      "detail": "Date range cannot exceed 7 days for inserted_at filters"
    }
  ]
}
```

**422 Unprocessable Entity** - Missing required filter
```json
{
  "errors": [
    {
      "status": "422",
      "title": "Validation Error",
      "detail": "At least one variation of filter[inserted_at] is required"
    }
  ]
}
```

<Note>
**Performance Tip:** Maximum date range for `inserted_at` filters is 7 days. For historical analysis, use multiple requests or export data to external storage.
</Note>

<Warning>
**Rate Limiting:** This endpoint is rate-limited to 100 requests per minute. For real-time monitoring, consider using webhooks or the `/findings/latest` endpoint.
</Warning>

<Tip>
Use `filter[delta]=new` to only retrieve findings discovered in the most recent scan, perfect for alerting on new security issues.
</Tip>