Snapshots
Use our REST API to manage your snapshots and fetch the snapshots details in real-time.
List 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=app_xxxxxxxxx'
Curl Request - Paginate snapshots using a cursor
curl -X GET 'https://percy.io/api/v1/snapshots?build_id=<build_id>&page\[cursor\]=<last_snapshot_id>' \
-H "Authorization: Token <read-only/full-access 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,
"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
▶ SHOW VALUESDetails of test session.
-
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
▶ SHOW VALUESDetails of test session.
-
self Integer
Time stamp when the build was last updated.
-
-
relationships Object
▶ SHOW VALUESDetails of test session.
-
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
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=app_xxxxxxxxx'
-
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,
"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
▶ SHOW VALUESDetails of test session.
-
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
▶ SHOW VALUESDetails of test session.
-
self Integer
Time stamp when the build was last updated.
-
-
relationships Object
▶ SHOW VALUESDetails of test session.
-
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.
-
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.