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

# Compare Findings

Search, filter, and compare security findings using the advanced Grid API.

## When to Use This Endpoint

Use this endpoint when you need to:

* **Compare Images**: Identify regressions between two binary file versions.
* **Advanced Filtering**: Filter findings by complex criteria not available in the simple list.
* **Export**: Retrieve large datasets of findings.

## Request

**Endpoint**

```
POST <BINARLY_API_URL>/api/v4/grids/findings:gridList
```

**Headers**

| Header          | Value                   |
| --------------- | ----------------------- |
| `Authorization` | `Bearer <access_token>` |
| `Content-Type`  | `application/json`      |

**Body**

| Field     | Required | Description                           |
| --------- | -------- | ------------------------------------- |
| `filters` | ✅        | Array of filter objects (see example) |

## Filter Reference

> \[!IMPORTANT] The grid API requires at least one scope filter (`productId` or `imageId`) to return results. Requests without a scope filter may return 400 Bad Request.

Supported filter fields:

| Field                 | Values                                                           | Description                                     |
| --------------------- | ---------------------------------------------------------------- | ----------------------------------------------- |
| `productId`           | `<product_id>`                                                   | **Required scope filter** - Product ID to query |
| `imageId`             | `<image_id>`                                                     | Alternative scope filter - Specific image ID    |
| `issueStatus`         | `new`, `inProgress`, `remediated`, `rejected`                    | Workflow status of the finding                  |
| `severity`            | `critical`, `high`, `medium`, `low`, `informational`             | Finding severity level                          |
| `findingType`         | `knownVulnerability`, `maliciousCode`, `dependencyVulnerability` | Type of finding                                 |
| `compareLeftImageId`  | `<image_id>`                                                     | **Baseline** image ID for comparison            |
| `compareRightImageId` | `<image_id>`                                                     | **Target** image ID for comparison              |

## Example Request - Compare Images

To identify what changed between a baseline and a target image:

```bash theme={null}
BASELINE_ID="01JQ..."
TARGET_ID="01JY..."

curl -s -X POST \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {"field": "compareLeftImageId", "value": "'"${BASELINE_ID}"'", "comparator": "equals"},
      {"field": "compareRightImageId", "value": "'"${TARGET_ID}"'", "comparator": "equals"},
      {"field": "issueStatus", "value": ["new", "inProgress"], "comparator": "in"}
    ]
  }' \
  "${BINARLY_API_URL}/api/v4/grids/findings:gridList"
```

> \[!TIP] The `issueStatus` filter requires the `in` comparator with an array of status values, not `equals` with a single string.

## Response

Returns a paginated list of findings with comparison status.

```json theme={null}
{
  "total": 5,
  "rows": [
    {
      "id": "finding_123",
      "pname": "OpenSSL Vulnerability",
      "severity": "high",
      "comparison": {
        "status": "new"
      }
    }
  ]
}
```

| Field   | Description                               |
| ------- | ----------------------------------------- |
| `total` | Total count of findings matching criteria |
| `rows`  | Array of finding objects                  |