Skip to main content
No Result Found
Connect & Get help from fellow developers on our Discord community. Ask the CommunityAsk the Community

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=auto_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

    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=auto_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

    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.

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





Thank you for your valuable feedback

Download Copy Check Circle