Snapshots

Use our REST API to manage your snapshots and fetch the snapshots details in real-time.

List snapshots

GET https://percy.io/api/v1/snapshots

Retrieves the list of snapshots for the given build_id.

Request parameters

Curl Request

curl --request GET \
     --url 'https://percy.io/api/v1/snapshots?build_id={build_id}' \
     --header 'Authorization: Token token=<PROJECT_TOKEN>'

Curl Request - Paginate snapshots using a cursor. Use a full-access or read-only Project token.

curl -X GET 'https://percy.io/api/v1/snapshots?build_id=<build_id>&page\[cursor\]=<last_snapshot_id>' \
  -H "Authorization: Token token=<PROJECT_TOKEN>"

build_id^* String

ID of the desired build.
filter[review-state-reason][] Array of strings

Array of review state reasons.
filter[snapshot-ids][] Array of integers

Array of snapshot IDs.
filter[search] String | null

Search snapshots by name.
page[limit] Integer | null

Specifies the maximum number of snapshots to return per page. Both the default and maximum values are 30. If a value greater than 30 is provided, it is capped at 30. If not specified, the API returns 30 snapshots by default.
page[cursor] Integer | null

Specifies the snapshot ID of the last snapshot from the previous page. Returns the next set of snapshots after this ID. If not provided, returns the first page.

Response attributes `200 OK` `JSON`

Response

{
  "data": [
    {
      "type": "snapshots",
      "id": "1xxxxxxxxxx",
      "attributes": {
        "name": "example_screenshot_1",
        "review-state": "unreviewed",
        "review-state-reason": "unreviewed_comparisons",
        "fingerprint": null,
        "total-open-comments": 0,
        "is-reintroduced": false,
        "enable-javascript": false,
        "enable-layout": false,
        "layout-warning": false,
        "renderer-layout-warning-text": null,
        "scope-selector": null,
        "display-name": null,
        "test-case-id": "1xx",
        "test-case-name": "Test case name"
      },
      "links": {
        "self": "/api/v1/snapshots/1xxxxxxxxxx"
      },
      "relationships": {
        "build": {
          "data": {
            "type": "builds",
            "id": "30453077"
          }
        },
        "latest-changed-ancestor": {
          "links": {
            "related": "/api/v1/snapshots/1xxxxxxxxxx/latest-changed-ancestor"
          }
        },
        "screenshots": {},
        "comparisons": {
          "data": [
            {
              "type": "comparisons",
              "id": "2xxxxxxxxxx"
            }
          ]
        },
        "ignored-regions": {
          "data": []
        },
        "missing-resources": {
          "links": {
            "self": "/api/v1/snapshots/1xxxxxxxxxx/relationships/missing-resources",
            "related": "/api/v1/snapshots/1xxxxxxxxxx/missing-resources"
          }
        },
        "test-case": {
          "links": {
            "self": "/api/v1/snapshots/<snapshot_id>/relationships/test-case",
            "related": "/api/v1/snapshots/<snapshot_id>/test-case"
          },
          "data": { "type": "test-cases", "id": "1xx" }
        }
      }
    }
  ],
  "included": [
    {
      "type": "comparisons",
      "id": "2xxxxxxxxxx",
      "attributes": {
        "state": "finished",
        "width": 1080,
        "diff-ratio": null,
        "ai-diff-ratio": 0.0329,
        "ai-failure-reason": null,
        "ai-processing-state": "completed",
        "recurring-diff-detection-status": "no-recurring-diff",
        "ai-details": {
          "ai-enabled": true,
          "ai-visual-diffs": 2,
          "ai-processing-status": "completed",
          "ai-summary": "Minor visual differences detected"
        },
        "diff-ratio-wo-context-diff": null,
        "ignored-top": 0,
        "ignored-bottom": 0,
        "external-debug-url": "https://automate.browserstack.com/builds/176755c63026fe2c0115c02ce45bf8643570f745/sessions/914a952f1dff93ef9459e01641dca80e010d961c",
        "new-and-unchanged-with-reviewed-baseline": false
      },
      "links": {
        "self": "/api/v1/comparisons/2xxxxxxxxxx"
      },
      "relationships": {
        "head-snapshot": {
          "links": {
            "related": "/api/v1/snapshots/1xxxxxxxxxx"
          }
        },
        "base-snapshot": {
          "links": {
            "related": "/api/v1/comparisons/2xxxxxxxxxx/base-snapshot"
          },
          "data": null
        },
        "head-screenshot": {
          "data": {
            "type": "screenshots",
            "id": "2xxxxxxxxxx"
          }
        },
        "head-build": {
          "data": {
            "type": "builds",
            "id": "30453077"
          }
        },
        "base-screenshot": {
          "data": null
        },
        "diff-image": {
          "data": null
        },
        "context-diff-image": {
          "data": null
        },
        "browser": {
          "data": null
        },
        "comparison-tag": {
          "data": {
            "type": "comparison-tags",
            "id": "2111"
          }
        }
      }
    },
    {
      "type": "screenshots",
      "id": "2xxxxxxxxxx",
      "links": {
        "self": "/api/v1/screenshots/2xxxxxxxxxx"
      },
      "relationships": {
        "snapshot": {
          "links": {
            "self": "/api/v1/screenshots/2xxxxxxxxxx/relationships/snapshot",
            "related": "/api/v1/screenshots/2xxxxxxxxxx/snapshot"
          }
        },
        "image": {
          "links": {
            "self": "/api/v1/screenshots/2xxxxxxxxxx/relationships/image",
            "related": "/api/v1/screenshots/2xxxxxxxxxx/image"
          },
          "data": {
            "type": "images",
            "id": "1xxxxxxxxxx"
          }
        }
      }
    },
    {
      "type": "images",
      "id": "1xxxxxxxxxx",
      "attributes": {
        "url": "https://images.percy.io/c00233f700147a9eaf33bfc0a6b492af36a6b5a853b32c119c7b0ba0f73ef76d",
        "width": 1080,
        "height": 2106
      },
      "links": {
        "self": "/api/v1/images/1xxxxxxxxxx"
      }
    },
    {
      "type": "comparison-tags",
      "id": "2111",
      "attributes": {
        "name": "Samsung Galaxy S22 Ultra",
        "slug": "samsung-galaxy-s22-ultra-e0a83d6e3362",
        "os-name": "Android",
        "os-version": "12",
        "width": 1080,
        "height": 1949,
        "orientation": "portrait",
        "browser-name": "chrome",
        "browser-version": "Samsung Galaxy S22 Ultra",
        "resolution": "1080 x 2317",
        "serial-number": null,
        "purchase-date": null,
        "location": null
      }
    }
  ]
}

attributes Object

Details of test session.

▶ SHOW VALUES
- name String
  
  Name of the snapshot.
- review-state String
  
  Specifies build review state approved or unreviewed. Expected values are unreviewed, approved, changes_requested, merged, rejected.
- review-state-reason Boolean
  
  Status flag for no-diffs or unreviewed comparisons. Expected values are unreviewed_snapshots, all_snapshots_approved, all_snapshots_approved_previously, no_diffs, auto_approved_branch, changes_requested_snapshot, changes_requested_snapshot_previously, missing_snapshots, user_merged, project_first_build, failed_snapshots, ignore_diff_setting, visual_monitoring_prod_build, design_build, user_rejected.
- fingerprint Integer
  
  SHA1 hash id.
- total-open-commits String
  
  Lists the number of open comments on a snapshot.
- is-reintroduced Boolean
  
  Reintroducing a snapshot.
- enable-javascript Boolean
  
  Returns true if enable-javascript:true has been added in the config file.
- enable-layout Boolean
  
  Returns true if enable-layout:true has been added in the config file.
- layout-warning String
  
  Specifies warning message (applicable only while layout is being tested).
- renderer-layout-warning-text String
  
  Specifies warning message during rendering (applicable only while layout is being tested).
- scope-selector Boolean
  
  Returns true if scope .selector was used while running percy.
- display-name String
  
  Specifies display name of the snapshot (applicable for monitoring projects)
- test-case-id Integer
  
  Specifies test case id.
- test-case-name String
  
  Specifies test case name.
links Object

Details of test session.

▶ SHOW VALUES
- self Integer
  
  Time stamp when the build was last updated.
relationships Object

Details of test session.

▶ SHOW VALUES
- build Object
  
  Specifies details of the build and API Endpoint to fetch.
- latest-changed-ancestor Object
  
  Data of the latest changed ancestor.
- screenshots Object
  
  Data of the screenshots.
- comparisons Object
  
  Data of the comparisons.
- ignore-regions Object
  
  Details of ignored regions.
- missing-resources Object
  
  Endpoints to access the missing-resources.

Get snapshot

GET https://percy.io/api/v1/snapshots/{snapshot_id}

Retrieves the snapshot details for the given snapshot_id.

Request parameters

Curl Request

curl --request GET \
     --url 'https://percy.io/api/v1/snapshots/snapshot_id' \
     --header 'Authorization: Token token=<PROJECT_TOKEN>'

snapshot_id^* String

ID for the desired snapshot.

Response attributes `200 OK` `JSON`

Response

{
  "data": {
    "type": "snapshots",
    "id": "1xxxxxxxxxx",
    "attributes": {
      "name": "example_screenshot_1",
      "review-state": "unreviewed",
      "review-state-reason": "unreviewed_comparisons",
      "fingerprint": null,
      "total-open-comments": 0,
      "is-reintroduced": false,
      "enable-javascript": false,
      "enable-layout": false,
      "layout-warning": false,
      "renderer-layout-warning-text": null,
      "scope-selector": null,
      "display-name": null,
      "test-case-id": "1xx",
      "test-case-name": "Test case name"
    },
    "links": {
      "self": "/api/v1/snapshots/1xxxxxxxxxx"
    },
    "relationships": {
      "build": {
        "data": {
          "type": "builds",
          "id": "30453077"
        }
      },
      "latest-changed-ancestor": {
        "links": {
          "related": "/api/v1/snapshots/1xxxxxxxxxx/latest-changed-ancestor"
        }
      },
      "screenshots": {},
      "comparisons": {
        "data": [
          {
            "type": "comparisons",
            "id": "2xxxxxxxxxx"
          }
        ]
      },
      "ignored-regions": {
        "data": []
      },
      "missing-resources": {
        "links": {
          "self": "/api/v1/snapshots/1xxxxxxxxxx/relationships/missing-resources",
          "related": "/api/v1/snapshots/1xxxxxxxxxx/missing-resources"
        }
      },
      "test-case": {
        "links": {
          "self": "/api/v1/snapshots/<snapshot_id>/relationships/test-case",
          "related": "/api/v1/snapshots/<snapshot_id>/test-case"
        },
        "data": { "type": "test-cases", "id": "1xx" }
      }
    }
  },
  "meta": {},
  "included": [
    {
      "type": "comparisons",
      "id": "2xxxxxxxxxx",
      "attributes": {
        "state": "finished",
        "width": 1080,
        "diff-ratio": null,
        "ai-diff-ratio": 0.0329,
        "ai-failure-reason": null,
        "ai-processing-state": "completed",
        "recurring-diff-detection-status": "no-recurring-diff",
        "ai-details": {
          "ai-enabled": true,
          "ai-visual-diffs": 2,
          "ai-processing-status": "completed",
          "ai-summary": "Minor visual differences detected"
        },
        "diff-ratio-wo-context-diff": null,
        "ignored-top": 0,
        "ignored-bottom": 0,
        "external-debug-url": "https://automate.browserstack.com/builds/176755c63026fe2c0115c02ce45bf8643570f745/sessions/914a952f1dff93ef9459e01641dca80e010d961c",
        "new-and-unchanged-with-reviewed-baseline": false
      },
      "links": {
        "self": "/api/v1/comparisons/2xxxxxxxxxx"
      },
      "relationships": {
        "head-snapshot": {
          "links": {
            "related": "/api/v1/snapshots/1xxxxxxxxxx"
          }
        },
        "base-snapshot": {
          "links": {
            "related": "/api/v1/comparisons/2xxxxxxxxxx/base-snapshot"
          },
          "data": null
        },
        "head-screenshot": {
          "data": {
            "type": "screenshots",
            "id": "2xxxxxxxxxx"
          }
        },
        "head-build": {
          "data": {
            "type": "builds",
            "id": "30453077"
          }
        },
        "base-screenshot": {
          "data": null
        },
        "diff-image": {
          "data": null
        },
        "context-diff-image": {
          "data": null
        },
        "browser": {
          "data": null
        },
        "comparison-tag": {
          "data": {
            "type": "comparison-tags",
            "id": "2111"
          }
        }
      }
    },
    {
      "type": "screenshots",
      "id": "2xxxxxxxxxx",
      "links": {
        "self": "/api/v1/screenshots/2xxxxxxxxxx"
      },
      "relationships": {
        "snapshot": {
          "links": {
            "self": "/api/v1/screenshots/2xxxxxxxxxx/relationships/snapshot",
            "related": "/api/v1/screenshots/2xxxxxxxxxx/snapshot"
          }
        },
        "image": {
          "links": {
            "self": "/api/v1/screenshots/2xxxxxxxxxx/relationships/image",
            "related": "/api/v1/screenshots/2xxxxxxxxxx/image"
          },
          "data": {
            "type": "images",
            "id": "1xxxxxxxxxx"
          }
        }
      }
    },
    {
      "type": "images",
      "id": "1xxxxxxxxxx",
      "attributes": {
        "url": "https://images.percy.io/c00233f700147a9eaf33bfc0a6b492af36a6b5a853b32c119c7b0ba0f73ef76d",
        "width": 1080,
        "height": 2106
      },
      "links": {
        "self": "/api/v1/images/1xxxxxxxxxx"
      }
    },
    {
      "type": "comparison-tags",
      "id": "2111",
      "attributes": {
        "name": "Samsung Galaxy S22 Ultra",
        "slug": "samsung-galaxy-s22-ultra-e0a83d6e3362",
        "os-name": "Android",
        "os-version": "12",
        "width": 1080,
        "height": 1949,
        "orientation": "portrait",
        "browser-name": "chrome",
        "browser-version": "Samsung Galaxy S22 Ultra",
        "resolution": "1080 x 2317",
        "serial-number": null,
        "purchase-date": null,
        "location": null
      }
    }
  ]
}

attributes Object

Details of test session.

▶ SHOW VALUES
- name String
  
  Name of the snapshot.
- review-state String
  
  Specifies build review state approved or unreviewed. Expected values are unreviewed, approved, changes_requested, merged, rejected.
- review-state-reason Boolean
  
  Status flag for no-diffs or unreviewed comparisons. Expected values are unreviewed_snapshots, all_snapshots_approved, all_snapshots_approved_previously, no_diffs, auto_approved_branch, changes_requested_snapshot, changes_requested_snapshot_previously, missing_snapshots, user_merged, project_first_build, failed_snapshots, ignore_diff_setting, visual_monitoring_prod_build, design_build, user_rejected.
- fingerprint Integer
  
  SHA1 hash id.
- total-open-commits String
  
  Lists the number of open comments on a snapshot.
- is-reintroduced Boolean
  
  Reintroducing a snapshot.
- enable-javascript Boolean
  
  Returns true if enable-javascript, true has been added in the config file.
- enable-layout Boolean
  
  Returns true if enable-layout:true has been added in the config file.
- layout-warning Boolean
  
  Specifies warning message (applicable only while layout is being tested).
- renderer-layout-warning-text String
  
  Specifies warning message during rendering (applicable only while layout is being tested).
- scope-selector Boolean
  
  Returns true if scope .selector was used while running percy.
- display-name String
  
  Specifies display name of the snapshot (applicable for monitoring projects)
- test-case-id Integer
  
  Specifies test case id.
- test-case-name Integer
  
  Specifies test case name.
links Object

Details of test session.

▶ SHOW VALUES
- self Integer
  
  Time stamp when the build was last updated.
relationships Object

Details of test session.

▶ SHOW VALUES
- build Object
  
  Specifies details of the build and API Endpoint to fetch.
- latest-changed-ancestor Object
  
  Data of the latest changed ancestor.
- screenshots Object
  
  Data of the screenshots.
- comparisons Object
  
  Data of the comparisons.
- ignore-regions Object
  
  Details of ignored regions.
- missing-resources Object
  
  Endpoints to access the missing-resources.
included:comparisons.attributes Object

Comparison attributes.

▶ SHOW VALUES
- state String
  
  Current state of the comparison.
- width Integer
  
  Width of the comparison.
- diff-ratio Float
  
  Ratio of differences detected.
- ai-diff-ratio Float
  
  AI-detected diff ratio.
- ai-failure-reason String
  
  Reason for AI failure detection.
- ai-processing-state String
  
  State of AI processing.
- recurring-diff-detection-status String
  
  Status of recurring diff detection.
- ai-details Object
  
  AI analysis details for the comparison.
  
  ▶ SHOW VALUES
  - ai-enabled Boolean
    
    Indicates if AI analysis is enabled for this comparison.
  - ai-visual-diffs Integer
    
    Number of AI-detected visual diffs.
  - ai-processing-status String
    
    Status of AI processing.
  - ai-summary String
    
    Summary of AI analysis findings.
- ignored-top Integer
  
  Ignored area from top.
- ignored-bottom Integer
  
  Ignored area from bottom.
- external-debug-url String
  
  External debug URL for the comparison.
- new-and-unchanged-with-reviewed-baseline Boolean
  
  Indicates if new and unchanged with reviewed baseline.

Did this page help you?

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Snapshots

List snapshots

Request parameters

build_id* String

filter[review-state-reason][] Array of strings

filter[snapshot-ids][] Array of integers

filter[search] String | null

page[limit] Integer | null

page[cursor] Integer | null

Response attributes 200 OK JSON

attributes Object

name String

review-state String

review-state-reason Boolean

fingerprint Integer

total-open-commits String

is-reintroduced Boolean

enable-javascript Boolean

enable-layout Boolean

layout-warning String

renderer-layout-warning-text String

scope-selector Boolean

display-name String

test-case-id Integer

test-case-name String

links Object

self Integer

relationships Object

build Object

latest-changed-ancestor Object

screenshots Object

comparisons Object

ignore-regions Object

missing-resources Object

Get snapshot

Request parameters

snapshot_id* String

Response attributes 200 OK JSON

attributes Object

name String

review-state String

review-state-reason Boolean

fingerprint Integer

total-open-commits String

is-reintroduced Boolean

enable-javascript Boolean

enable-layout Boolean

layout-warning Boolean

renderer-layout-warning-text String

scope-selector Boolean

display-name String

test-case-id Integer

test-case-name Integer

links Object

self Integer

relationships Object

build Object

latest-changed-ancestor Object

screenshots Object

comparisons Object

ignore-regions Object

missing-resources Object

included:comparisons.attributes Object

state String

width Integer

diff-ratio Float

ai-diff-ratio Float

ai-failure-reason String

ai-processing-state String

recurring-diff-detection-status String

ai-details Object

ai-enabled Boolean

ai-visual-diffs Integer

ai-processing-status String

ai-summary String

ignored-top Integer

ignored-bottom Integer

external-debug-url String

new-and-unchanged-with-reviewed-baseline Boolean

We're sorry to hear that. Please share your feedback so we can do better

build_id^* String

Response attributes `200 OK` `JSON`

snapshot_id^* String

Response attributes `200 OK` `JSON`