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

Builds

Each build represents a logical grouping of test sessions executed on Percy. Use our REST API to manage your builds and fetch the build details in real-time.

List recent builds

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

Retrieves the list of builds associated with your username and access key from the last 30 days.

Request parameters

Curl Request - Builds

curl --request GET \
     --url 'https://percy.io/api/v1/builds' \
     --header 'Authorization: Token token=auto_xxxxxx'

Curl Request - SHA

curl --request GET \
  --url 'https://percy.io/api/v1/builds\?filter%5Bsha%5D\=<SHA>' \
  --header 'Authorization: Token token=<PROJECT_TOKEN>'

Curl Request - Branch Name

curl --request GET \
    --url 'https://percy.io/api/v1/builds\?filter%5Bbranch%5D\=<BRANCH-NAME>' \
    --header 'Authorization: Token token=<PROJECT_TOKEN>'

Curl Request - Build state

curl --request GET \
  --url 'https://percy.io/api/v1/builds\?filter%5Bstate%5D\=<VALID BUILD STATE>' \
  --header 'Authorization: Token token=<PROJECT_TOKEN>'

Curl Request - Paginate snapshots using a cursor

curl -X GET 'https://percy.io/api/v1/builds?project_id=<project_id>&page\[cursor\]=<build_id>&page\[limit\]=30' \               
  -H "Authorization: Token <project full-access/read-only token>"

  • filter[sha] String

    Applies a filter based on the Secure Hash Algorithm (SHA).

  • filter[shas][] Array of strings

    Filter records using an array of SHA values.

  • filter[branch] String

    Filter data based on a specified branch name.

  • filter[state] String

    Filter data based on a specified build state.
    VALID_STATES = processing, finished, failed, waiting.

  • page[limit] Integer | null

    Specifies the maximum number of builds 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 builds by default.

  • page[cursor] Integer | null

    Takes a build ID as input and returns all builds with a build ID less than the provided value.

Response attributes 200 OK JSON

Response

{
  "data": [
    {
      "type": "builds",
      "id": "3xxxxxx",
      "attributes": {
        "branch": "unknown-branch",
        "type": "automate",
        "build-number": 9,
        "partial": false,
        "web-url": "https://percy.io/9xxxxxx/test-auto/builds/3xxxxxx",
        "commit-html-url": null,
        "branch-html-url": null,
        "pull-request-html-url": null,
        "state": "finished",
        "review-state": "unreviewed",
        "review-state-reason": "unreviewed_snapshots",
        "is-pull-request": false,
        "pull-request-number": null,
        "pull-request-title": null,
        "user-agent": "Percy/v1 @percy/client/1.27.1 @percy/cli-exec/1.27.1 percy-selenium-python/2.0.0-alpha.0 (node/v20.5.1; selenium/4.8.3; python/3.11.5)",
        "total-snapshots": 1,
        "total-snapshots-requesting-changes": 0,
        "total-snapshots-unreviewed": 1,
        "total-comparisons": 1,
        "total-comparisons-finished": 1,
        "total-comparisons-diff": 1,
        "total-open-comments": 0,
        "failed-snapshots-count": 0,
        "failure-reason": null,
        "failure-details": null,
        "parallel-nonce": null,
        "parallel-total-shards": null,
        "finished-at": "2023-10-03T10:17:51.000Z",
        "finalized-at": "2023-10-03T10:17:50.000Z",
        "approved-at": null,
        "created-at": "2023-10-03T10:17:20.000Z",
        "updated-at": "2023-10-03T10:17:51.000Z"
      },
      "links": {
        "self": "/api/v1/builds/3xxxxxx"
      },
      "relationships": {
        "project": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/project",
            "related": "/api/v1/builds/3xxxxxx/project"
          },
          "data": {
            "type": "projects",
            "id": "3xxxxxx"
          }
        },
        "commit": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/commit",
            "related": "/api/v1/builds/3xxxxxx/commit"
          },
          "data": null
        },
        "repo": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/repo",
            "related": "/api/v1/builds/3xxxxxx/repo"
          },
          "data": null
        },
        "base-build": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/base-build",
            "related": "/api/v1/builds/3xxxxxx/base-build"
          },
          "data": null
        },
        "base-build-strategy": {},
        "approved-by": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/approved-by",
            "related": "/api/v1/builds/3xxxxxx/approved-by"
          },
          "data": null
        },
        "snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/snapshots",
            "related": "/api/v1/builds/3xxxxxx/snapshots"
          }
        },
        "comparisons": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/comparisons",
            "related": "/api/v1/builds/3xxxxxx/comparisons"
          }
        },
        "browsers": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/browsers",
            "related": "/api/v1/builds/3xxxxxx/browsers"
          },
          "data": []
        },
        "removed-snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/removed-snapshots",
            "related": "/api/v1/builds/3xxxxxx/removed-snapshots"
          }
        },
        "failed-snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/failed-snapshots",
            "related": "/api/v1/builds/3xxxxxx/failed-snapshots"
          }
        },
        "missing-resources": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/missing-resources",
            "related": "/api/v1/builds/3xxxxxx/missing-resources"
          }
        }
      },
      "meta": {
        "finalize-link": "/api/v1/builds/3xxxxxx/finalize",
        "approve-link": "/api/v1/builds/3xxxxxx/approve"
      }
    },
    {
      "type": "builds",
      "id": "3xxxxxx",
      "attributes": {
        "branch": "unknown-branch",
        "type": "automate",
        "build-number": 8,
        "partial": false,
        "web-url": "https://percy.io/9xxxxxxx/test-auto/builds/3xxxxxx",
        "commit-html-url": null,
        "branch-html-url": null,
        "pull-request-html-url": null,
        "state": "failed",
        "review-state": null,
        "review-state-reason": null,
        "is-pull-request": false,
        "pull-request-number": null,
        "pull-request-title": null,
        "user-agent": "Percy/v1 @percy/client/1.27.1 @percy/cli-exec/1.27.1 (node/v20.5.1)",
        "total-snapshots": 0,
        "total-snapshots-requesting-changes": 0,
        "total-snapshots-unreviewed": null,
        "total-comparisons": 0,
        "total-comparisons-finished": 0,
        "total-comparisons-diff": 0,
        "total-open-comments": 0,
        "failed-snapshots-count": 0,
        "failure-reason": "no_snapshots",
        "failure-details": null,
        "parallel-nonce": null,
        "parallel-total-shards": null,
        "finished-at": null,
        "finalized-at": "2023-10-03T10:17:12.000Z",
        "approved-at": null,
        "created-at": "2023-10-03T10:17:11.000Z",
        "updated-at": "2023-10-03T10:17:12.000Z"
      },
      "links": {
        "self": "/api/v1/builds/3xxxxxx"
      },
      "relationships": {
        "project": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/project",
            "related": "/api/v1/builds/3xxxxxx/project"
          },
          "data": {
            "type": "projects",
            "id": "4xxxxxx"
          }
        },
        "commit": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/commit",
            "related": "/api/v1/builds/3xxxxxx/commit"
          },
          "data": null
        },
        "repo": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/repo",
            "related": "/api/v1/builds/3xxxxxx/repo"
          },
          "data": null
        },
        "base-build": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/base-build",
            "related": "/api/v1/builds/3xxxxxx/base-build"
          },
          "data": null
        },
        "base-build-strategy": {},
        "approved-by": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/approved-by",
            "related": "/api/v1/builds/3xxxxxx/approved-by"
          },
          "data": null
        },
        "snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/snapshots",
            "related": "/api/v1/builds/3xxxxxx/snapshots"
          }
        },
        "comparisons": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/comparisons",
            "related": "/api/v1/builds/3xxxxxx/comparisons"
          }
        },
        "browsers": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/browsers",
            "related": "/api/v1/builds/3xxxxxx/browsers"
          },
          "data": []
        },
        "removed-snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/removed-snapshots",
            "related": "/api/v1/builds/3xxxxxx/removed-snapshots"
          }
        },
        "failed-snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/failed-snapshots",
            "related": "/api/v1/builds/3xxxxxx/failed-snapshots"
          }
        },
        "missing-resources": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/missing-resources",
            "related": "/api/v1/builds/3xxxxxx/missing-resources"
          }
        }
      },
      "meta": {
        "finalize-link": "/api/v1/builds/3xxxxxx/finalize",
        "approve-link": "/api/v1/builds/3xxxxxx/approve"
      }
    },
    {
      "type": "builds",
      "id": "3xxxxxx",
      "attributes": {
        "branch": "unknown-branch",
        "type": "automate",
        "build-number": 7,
        "partial": false,
        "web-url": "https://percy.io/9xxxxxxxx/test-auto/builds/3xxxxxx",
        "commit-html-url": null,
        "branch-html-url": null,
        "pull-request-html-url": null,
        "state": "finished",
        "review-state": "unreviewed",
        "review-state-reason": "unreviewed_snapshots",
        "is-pull-request": false,
        "pull-request-number": null,
        "pull-request-title": null,
        "user-agent": "Percy/v1 @percy/client/1.27.1 @percy/cli-exec/1.27.1 percy-selenium-python/2.0.0-alpha.0 (node/v20.5.1; selenium/4.8.3; python/3.11.5)",
        "total-snapshots": 1,
        "total-snapshots-requesting-changes": 0,
        "total-snapshots-unreviewed": 1,
        "total-comparisons": 1,
        "total-comparisons-finished": 1,
        "total-comparisons-diff": 1,
        "total-open-comments": 0,
        "failed-snapshots-count": 0,
        "failure-reason": null,
        "failure-details": null,
        "parallel-nonce": null,
        "parallel-total-shards": null,
        "finished-at": "2023-09-21T14:25:26.000Z",
        "finalized-at": "2023-09-21T14:25:23.000Z",
        "approved-at": null,
        "created-at": "2023-09-21T14:25:01.000Z",
        "updated-at": "2023-09-21T14:25:26.000Z"
      },
      "links": {
        "self": "/api/v1/builds/3xxxxxx"
      },
      "relationships": {
        "project": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/project",
            "related": "/api/v1/builds/3xxxxxx/project"
          },
          "data": {
            "type": "projects",
            "id": "4xxxxxx"
          }
        },
        "commit": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/commit",
            "related": "/api/v1/builds/3xxxxxx/commit"
          },
          "data": null
        },
        "repo": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/repo",
            "related": "/api/v1/builds/3xxxxxx/repo"
          },
          "data": null
        },
        "base-build": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/base-build",
            "related": "/api/v1/builds/3xxxxxx/base-build"
          },
          "data": null
        },
        "base-build-strategy": {},
        "approved-by": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/approved-by",
            "related": "/api/v1/builds/3xxxxxx/approved-by"
          },
          "data": null
        },
        "snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/snapshots",
            "related": "/api/v1/builds/3xxxxxx/snapshots"
          }
        },
        "comparisons": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/comparisons",
            "related": "/api/v1/builds/3xxxxxx/comparisons"
          }
        },
        "browsers": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/browsers",
            "related": "/api/v1/builds/3xxxxxx/browsers"
          },
          "data": []
        },
        "removed-snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/removed-snapshots",
            "related": "/api/v1/builds/3xxxxxx/removed-snapshots"
          }
        },
        "failed-snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/failed-snapshots",
            "related": "/api/v1/builds/3xxxxxx/failed-snapshots"
          }
        },
        "missing-resources": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/missing-resources",
            "related": "/api/v1/builds/3xxxxxx/missing-resources"
          }
        }
      },
      "meta": {
        "finalize-link": "/api/v1/builds/3xxxxxx/finalize",
        "approve-link": "/api/v1/builds/3xxxxxx/approve"
      }
    },
    {
      "type": "builds",
      "id": "3xxxxxx",
      "attributes": {
        "branch": "unknown-branch",
        "type": "automate",
        "build-number": 6,
        "partial": false,
        "web-url": "https://percy.io/9xxxxxxxx/test-auto/builds/3xxxxxx",
        "commit-html-url": null,
        "branch-html-url": null,
        "pull-request-html-url": null,
        "state": "failed",
        "review-state": null,
        "review-state-reason": null,
        "is-pull-request": false,
        "pull-request-number": null,
        "pull-request-title": null,
        "user-agent": "Percy/v1 @percy/client/1.27.1 @percy/cli-exec/1.27.1 (node/v20.5.1)",
        "total-snapshots": 0,
        "total-snapshots-requesting-changes": 0,
        "total-snapshots-unreviewed": null,
        "total-comparisons": 0,
        "total-comparisons-finished": 0,
        "total-comparisons-diff": 0,
        "total-open-comments": 0,
        "failed-snapshots-count": 0,
        "failure-reason": "no_snapshots",
        "failure-details": null,
        "parallel-nonce": null,
        "parallel-total-shards": null,
        "finished-at": null,
        "finalized-at": "2023-09-21T14:24:54.000Z",
        "approved-at": null,
        "created-at": "2023-09-21T14:22:15.000Z",
        "updated-at": "2023-09-21T14:24:54.000Z"
      },
      "links": {
        "self": "/api/v1/builds/3xxxxxx"
      },
      "relationships": {
        "project": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/project",
            "related": "/api/v1/builds/3xxxxxx/project"
          },
          "data": {
            "type": "projects",
            "id": "4xxxxxx"
          }
        },
        "commit": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/commit",
            "related": "/api/v1/builds/3xxxxxx/commit"
          },
          "data": null
        },
        "repo": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/repo",
            "related": "/api/v1/builds/3xxxxxx/repo"
          },
          "data": null
        },
        "base-build": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/base-build",
            "related": "/api/v1/builds/3xxxxxx/base-build"
          },
          "data": null
        },
        "base-build-strategy": {},
        "approved-by": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/approved-by",
            "related": "/api/v1/builds/3xxxxxx/approved-by"
          },
          "data": null
        },
        "snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/snapshots",
            "related": "/api/v1/builds/3xxxxxx/snapshots"
          }
        },
        "comparisons": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/comparisons",
            "related": "/api/v1/builds/3xxxxxx/comparisons"
          }
        },
        "browsers": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/browsers",
            "related": "/api/v1/builds/3xxxxxx/browsers"
          },
          "data": []
        },
        "removed-snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/removed-snapshots",
            "related": "/api/v1/builds/3xxxxxx/removed-snapshots"
          }
        },
        "failed-snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/failed-snapshots",
            "related": "/api/v1/builds/3xxxxxx/failed-snapshots"
          }
        },
        "missing-resources": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/missing-resources",
            "related": "/api/v1/builds/3xxxxxx/missing-resources"
          }
        }
      },
      "meta": {
        "finalize-link": "/api/v1/builds/3xxxxxx/finalize",
        "approve-link": "/api/v1/builds/3xxxxxx/approve"
      }
    },
    {
      "type": "builds",
      "id": "3xxxxxx",
      "attributes": {
        "branch": "unknown-branch",
        "type": "automate",
        "build-number": 5,
        "partial": false,
        "web-url": "https://percy.io/9xxxxxxxx/test-auto/builds/3xxxxxx",
        "commit-html-url": null,
        "branch-html-url": null,
        "pull-request-html-url": null,
        "state": "finished",
        "review-state": "unreviewed",
        "review-state-reason": "unreviewed_snapshots",
        "is-pull-request": false,
        "pull-request-number": null,
        "pull-request-title": null,
        "user-agent": "Percy/v1 @percy/client/1.27.1 @percy/cli-exec/1.27.1 percy-selenium-python/2.0.0-alpha.0 (node/v20.5.1; selenium/4.8.3; python/3.11.5)",
        "total-snapshots": 1,
        "total-snapshots-requesting-changes": 0,
        "total-snapshots-unreviewed": 1,
        "total-comparisons": 1,
        "total-comparisons-finished": 1,
        "total-comparisons-diff": 1,
        "total-open-comments": 0,
        "failed-snapshots-count": 0,
        "failure-reason": null,
        "failure-details": null,
        "parallel-nonce": null,
        "parallel-total-shards": null,
        "finished-at": "2023-09-21T14:20:50.000Z",
        "finalized-at": "2023-09-21T14:20:46.000Z",
        "approved-at": null,
        "created-at": "2023-09-21T14:20:05.000Z",
        "updated-at": "2023-09-21T14:20:51.000Z"
      },
      "links": {
        "self": "/api/v1/builds/3xxxxxx"
      },
      "relationships": {
        "project": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/project",
            "related": "/api/v1/builds/3xxxxxx/project"
          },
          "data": {
            "type": "projects",
            "id": "4xxxxxx"
          }
        },
        "commit": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/commit",
            "related": "/api/v1/builds/3xxxxxx/commit"
          },
          "data": null
        },
        "repo": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/repo",
            "related": "/api/v1/builds/3xxxxxx/repo"
          },
          "data": null
        },
        "base-build": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/base-build",
            "related": "/api/v1/builds/3xxxxxx/base-build"
          },
          "data": null
        },
        "base-build-strategy": {},
        "approved-by": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/approved-by",
            "related": "/api/v1/builds/3xxxxxx/approved-by"
          },
          "data": null
        },
        "snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/snapshots",
            "related": "/api/v1/builds/3xxxxxx/snapshots"
          }
        },
        "comparisons": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/comparisons",
            "related": "/api/v1/builds/3xxxxxx/comparisons"
          }
        },
        "browsers": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/browsers",
            "related": "/api/v1/builds/3xxxxxx/browsers"
          },
          "data": []
        },
        "removed-snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/removed-snapshots",
            "related": "/api/v1/builds/3xxxxxx/removed-snapshots"
          }
        },
        "failed-snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/failed-snapshots",
            "related": "/api/v1/builds/3xxxxxx/failed-snapshots"
          }
        },
        "missing-resources": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/missing-resources",
            "related": "/api/v1/builds/3xxxxxx/missing-resources"
          }
        }
      },
      "meta": {
        "finalize-link": "/api/v1/builds/3xxxxxx/finalize",
        "approve-link": "/api/v1/builds/3xxxxxx/approve"
      }
    },
    {
      "type": "builds",
      "id": "3xxxxxx",
      "attributes": {
        "branch": "unknown-branch",
        "type": "automate",
        "build-number": 4,
        "partial": false,
        "web-url": "https://percy.io/9xxxxxxxx/test-auto/builds/3xxxxxx",
        "commit-html-url": null,
        "branch-html-url": null,
        "pull-request-html-url": null,
        "state": "failed",
        "review-state": null,
        "review-state-reason": null,
        "is-pull-request": false,
        "pull-request-number": null,
        "pull-request-title": null,
        "user-agent": "Percy/v1 @percy/client/1.27.1 @percy/cli-exec/1.27.1 (node/v20.5.1)",
        "total-snapshots": 0,
        "total-snapshots-requesting-changes": 0,
        "total-snapshots-unreviewed": null,
        "total-comparisons": 0,
        "total-comparisons-finished": 0,
        "total-comparisons-diff": 0,
        "total-open-comments": 0,
        "failed-snapshots-count": 0,
        "failure-reason": "no_snapshots",
        "failure-details": null,
        "parallel-nonce": null,
        "parallel-total-shards": null,
        "finished-at": null,
        "finalized-at": "2023-09-21T14:20:03.000Z",
        "approved-at": null,
        "created-at": "2023-09-21T14:15:31.000Z",
        "updated-at": "2023-09-21T14:20:03.000Z"
      },
      "links": {
        "self": "/api/v1/builds/3xxxxxx"
      },
      "relationships": {
        "project": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/project",
            "related": "/api/v1/builds/3xxxxxx/project"
          },
          "data": {
            "type": "projects",
            "id": "4xxxxxx"
          }
        },
        "commit": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/commit",
            "related": "/api/v1/builds/3xxxxxx/commit"
          },
          "data": null
        },
        "repo": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/repo",
            "related": "/api/v1/builds/3xxxxxx/repo"
          },
          "data": null
        },
        "base-build": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/base-build",
            "related": "/api/v1/builds/3xxxxxx/base-build"
          },
          "data": null
        },
        "base-build-strategy": {},
        "approved-by": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/approved-by",
            "related": "/api/v1/builds/3xxxxxx/approved-by"
          },
          "data": null
        },
        "snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/snapshots",
            "related": "/api/v1/builds/3xxxxxx/snapshots"
          }
        },
        "comparisons": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/comparisons",
            "related": "/api/v1/builds/3xxxxxx/comparisons"
          }
        },
        "browsers": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/browsers",
            "related": "/api/v1/builds/3xxxxxx/browsers"
          },
          "data": []
        },
        "removed-snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/removed-snapshots",
            "related": "/api/v1/builds/3xxxxxx/removed-snapshots"
          }
        },
        "failed-snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/failed-snapshots",
            "related": "/api/v1/builds/3xxxxxx/failed-snapshots"
          }
        },
        "missing-resources": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/missing-resources",
            "related": "/api/v1/builds/3xxxxxx/missing-resources"
          }
        }
      },
      "meta": {
        "finalize-link": "/api/v1/builds/3xxxxxx/finalize",
        "approve-link": "/api/v1/builds/3xxxxxx/approve"
      }
    },
    {
      "type": "builds",
      "id": "3xxxxxx",
      "attributes": {
        "branch": "unknown-branch",
        "type": "automate",
        "build-number": 3,
        "partial": false,
        "web-url": "https://percy.io/9xxxxxxxx/test-auto/builds/3xxxxxx",
        "commit-html-url": null,
        "branch-html-url": null,
        "pull-request-html-url": null,
        "state": "failed",
        "review-state": null,
        "review-state-reason": null,
        "is-pull-request": false,
        "pull-request-number": null,
        "pull-request-title": null,
        "user-agent": "Percy/v1 @percy/client/1.27.1 @percy/cli-exec/1.27.1 (node/v20.5.1)",
        "total-snapshots": 0,
        "total-snapshots-requesting-changes": 0,
        "total-snapshots-unreviewed": null,
        "total-comparisons": 0,
        "total-comparisons-finished": 0,
        "total-comparisons-diff": 0,
        "total-open-comments": 0,
        "failed-snapshots-count": 0,
        "failure-reason": "no_snapshots",
        "failure-details": null,
        "parallel-nonce": null,
        "parallel-total-shards": null,
        "finished-at": null,
        "finalized-at": "2023-09-21T14:14:37.000Z",
        "approved-at": null,
        "created-at": "2023-09-21T14:14:10.000Z",
        "updated-at": "2023-09-21T14:14:37.000Z"
      },
      "links": {
        "self": "/api/v1/builds/3xxxxxx"
      },
      "relationships": {
        "project": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/project",
            "related": "/api/v1/builds/3xxxxxx/project"
          },
          "data": {
            "type": "projects",
            "id": "4xxxxxx"
          }
        },
        "commit": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/commit",
            "related": "/api/v1/builds/3xxxxxx/commit"
          },
          "data": null
        },
        "repo": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/repo",
            "related": "/api/v1/builds/3xxxxxx/repo"
          },
          "data": null
        },
        "base-build": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/base-build",
            "related": "/api/v1/builds/3xxxxxx/base-build"
          },
          "data": null
        },
        "base-build-strategy": {},
        "approved-by": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/approved-by",
            "related": "/api/v1/builds/3xxxxxx/approved-by"
          },
          "data": null
        },
        "snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/snapshots",
            "related": "/api/v1/builds/3xxxxxx/snapshots"
          }
        },
        "comparisons": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/comparisons",
            "related": "/api/v1/builds/3xxxxxx/comparisons"
          }
        },
        "browsers": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/browsers",
            "related": "/api/v1/builds/3xxxxxx/browsers"
          },
          "data": []
        },
        "removed-snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/removed-snapshots",
            "related": "/api/v1/builds/3xxxxxx/removed-snapshots"
          }
        },
        "failed-snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/failed-snapshots",
            "related": "/api/v1/builds/3xxxxxx/failed-snapshots"
          }
        },
        "missing-resources": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/missing-resources",
            "related": "/api/v1/builds/3xxxxxx/missing-resources"
          }
        }
      },
      "meta": {
        "finalize-link": "/api/v1/builds/3xxxxxx/finalize",
        "approve-link": "/api/v1/builds/3xxxxxx/approve"
      }
    },
    {
      "type": "builds",
      "id": "3xxxxxx",
      "attributes": {
        "branch": "unknown-branch",
        "type": "automate",
        "build-number": 2,
        "partial": false,
        "web-url": "https://percy.io/9xxxxxxxx/test-auto/builds/3xxxxxx",
        "commit-html-url": null,
        "branch-html-url": null,
        "pull-request-html-url": null,
        "state": "finished",
        "review-state": "unreviewed",
        "review-state-reason": "unreviewed_snapshots",
        "is-pull-request": false,
        "pull-request-number": null,
        "pull-request-title": null,
        "user-agent": "Percy/v1 @percy/client/1.27.1 @percy/cli-exec/1.27.1 percy-selenium-python/2.0.0-alpha.0 (node/v20.5.1; selenium/4.8.3; python/3.11.5)",
        "total-snapshots": 1,
        "total-snapshots-requesting-changes": 0,
        "total-snapshots-unreviewed": 1,
        "total-comparisons": 1,
        "total-comparisons-finished": 1,
        "total-comparisons-diff": 1,
        "total-open-comments": 0,
        "failed-snapshots-count": 0,
        "failure-reason": null,
        "failure-details": null,
        "parallel-nonce": null,
        "parallel-total-shards": null,
        "finished-at": "2023-09-21T07:54:54.000Z",
        "finalized-at": "2023-09-21T07:54:54.000Z",
        "approved-at": null,
        "created-at": "2023-09-21T07:54:24.000Z",
        "updated-at": "2023-09-21T07:54:54.000Z"
      },
      "links": {
        "self": "/api/v1/builds/3xxxxxx"
      },
      "relationships": {
        "project": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/project",
            "related": "/api/v1/builds/3xxxxxx/project"
          },
          "data": {
            "type": "projects",
            "id": "4xxxxxx"
          }
        },
        "commit": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/commit",
            "related": "/api/v1/builds/3xxxxxx/commit"
          },
          "data": null
        },
        "repo": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/repo",
            "related": "/api/v1/builds/3xxxxxx/repo"
          },
          "data": null
        },
        "base-build": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/base-build",
            "related": "/api/v1/builds/3xxxxxx/base-build"
          },
          "data": null
        },
        "base-build-strategy": {},
        "approved-by": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/approved-by",
            "related": "/api/v1/builds/3xxxxxx/approved-by"
          },
          "data": null
        },
        "snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/snapshots",
            "related": "/api/v1/builds/3xxxxxx/snapshots"
          }
        },
        "comparisons": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/comparisons",
            "related": "/api/v1/builds/3xxxxxx/comparisons"
          }
        },
        "browsers": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/browsers",
            "related": "/api/v1/builds/3xxxxxx/browsers"
          },
          "data": []
        },
        "removed-snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/removed-snapshots",
            "related": "/api/v1/builds/3xxxxxx/removed-snapshots"
          }
        },
        "failed-snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/failed-snapshots",
            "related": "/api/v1/builds/3xxxxxx/failed-snapshots"
          }
        },
        "missing-resources": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/missing-resources",
            "related": "/api/v1/builds/3xxxxxx/missing-resources"
          }
        }
      },
      "meta": {
        "finalize-link": "/api/v1/builds/3xxxxxx/finalize",
        "approve-link": "/api/v1/builds/3xxxxxx/approve"
      }
    },
    {
      "type": "builds",
      "id": "3xxxxxx",
      "attributes": {
        "branch": "unknown-branch",
        "type": "automate",
        "build-number": 1,
        "partial": false,
        "web-url": "https://percy.io/9xxxxxxxx/test-auto/builds/3xxxxxx",
        "commit-html-url": null,
        "branch-html-url": null,
        "pull-request-html-url": null,
        "state": "finished",
        "review-state": "unreviewed",
        "review-state-reason": "unreviewed_snapshots",
        "is-pull-request": false,
        "pull-request-number": null,
        "pull-request-title": null,
        "user-agent": "Percy/v1 @percy/client/1.27.1 @percy/cli-exec/1.27.1 percy-selenium-python/2.0.0-alpha.0 (node/v20.5.1; selenium/4.8.3; python/3.11.5)",
        "total-snapshots": 1,
        "total-snapshots-requesting-changes": 0,
        "total-snapshots-unreviewed": 1,
        "total-comparisons": 1,
        "total-comparisons-finished": 1,
        "total-comparisons-diff": 1,
        "total-open-comments": 0,
        "failed-snapshots-count": 0,
        "failure-reason": null,
        "failure-details": null,
        "parallel-nonce": null,
        "parallel-total-shards": null,
        "finished-at": "2023-09-21T07:49:04.000Z",
        "finalized-at": "2023-09-21T07:49:02.000Z",
        "approved-at": null,
        "created-at": "2023-09-21T07:46:11.000Z",
        "updated-at": "2023-09-21T07:49:04.000Z"
      },
      "links": {
        "self": "/api/v1/builds/3xxxxxx"
      },
      "relationships": {
        "project": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/project",
            "related": "/api/v1/builds/3xxxxxx/project"
          },
          "data": {
            "type": "projects",
            "id": "4xxxxxx"
          }
        },
        "commit": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/commit",
            "related": "/api/v1/builds/3xxxxxx/commit"
          },
          "data": null
        },
        "repo": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/repo",
            "related": "/api/v1/builds/3xxxxxx/repo"
          },
          "data": null
        },
        "base-build": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/base-build",
            "related": "/api/v1/builds/3xxxxxx/base-build"
          },
          "data": null
        },
        "base-build-strategy": {},
        "approved-by": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/approved-by",
            "related": "/api/v1/builds/3xxxxxx/approved-by"
          },
          "data": null
        },
        "snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/snapshots",
            "related": "/api/v1/builds/3xxxxxx/snapshots"
          }
        },
        "comparisons": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/comparisons",
            "related": "/api/v1/builds/3xxxxxx/comparisons"
          }
        },
        "browsers": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/browsers",
            "related": "/api/v1/builds/3xxxxxx/browsers"
          },
          "data": []
        },
        "removed-snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/removed-snapshots",
            "related": "/api/v1/builds/3xxxxxx/removed-snapshots"
          }
        },
        "failed-snapshots": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/failed-snapshots",
            "related": "/api/v1/builds/3xxxxxx/failed-snapshots"
          }
        },
        "missing-resources": {
          "links": {
            "self": "/api/v1/builds/3xxxxxx/relationships/missing-resources",
            "related": "/api/v1/builds/3xxxxxx/missing-resources"
          }
        }
      },
      "meta": {
        "finalize-link": "/api/v1/builds/3xxxxxx/finalize",
        "approve-link": "/api/v1/builds/3xxxxxx/approve"
      }
    }
  ],
  "included": [
    {
      "type": "projects",
      "id": "4xxxxxx",
      "attributes": {
        "name": "test-auto",
        "slug": "test-auto",
        "type": "automate",
        "full-slug": "9xxxxxxxx/test-auto",
        "is-enabled": true,
        "diff-base": "automatic",
        "auto-approve-branch-filter": "",
        "approval-required-branch-filter": "*",
        "default-base-branch": "master",
        "updated-at": "2023-10-03T10:17:51.000Z",
        "publicly-readable": false,
        "is-demo": false,
        "is-auto-browser-upgrade": true,
        "wait-for-base-build": false,
        "current-period-usage": 5,
        "screenshot-limit": null,
        "workflow": "git",
        "diff-sensitivity-level": 2
      },
      "links": {
        "self": "/api/v1/projects/9xxxxxxxx/test-auto"
      },
      "relationships": {
        "organization": {
          "links": {
            "related": "/api/v1/projects/9xxxxxxxx/test-auto/organization"
          },
          "data": {
            "type": "organizations",
            "id": "30412"
          }
        },
        "repo": {
          "links": {
            "related": "/api/v1/projects/9xxxxxxxx/test-auto/repo"
          },
          "data": null
        },
        "builds": {
          "links": {
            "related": "/api/v1/builds?project_id=4xxxxxx"
          }
        },
        "tokens": {
          "links": {
            "related": "/api/v1/projects/9xxxxxxxx/test-auto/tokens"
          }
        },
        "browser-targets": {
          "data": []
        },
        "project-browser-targets": {
          "data": []
        },
        "webhook-configs": {
          "data": []
        }
      }
    }
  ]
}

  • attributes Object

    Details of test session.

    ▶ SHOW VALUES

    • branch String

      Git branch name.

    • type String

      Specifies if the project is a Web or App project.

    • build-number Integer

      Specifies the build number.

    • partial Boolean

      Specifies if its a partial build.

    • web-url String

      Path to the build url.

    • commit-html-url String

      Path to the commit url.

    • branch-html-url String

      Path to the branch url.

    • pull-request-html-url String

      Path to the pull-request url.

    • state String

      Specifies if the build is finished.

    • review-state String

      Represents the changes_requested or approved review state. Expected values are unreviewed, approved, changes_requested, merged, rejected.

    • review-state-reason String

      Specifies the reason for changes requested or approved. 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.

    • is-pull-request Boolean

      Specifies if there is a pull-request.

    • pull-request-number Integer

      Lists the pull request number.

    • pull-request-title String

      Specifies the pull request title.

    • user-agent String

      Percy CLI user agent.

    • total-snapshots Integer

      Specifies the total snapshot count.

    • total-snapshosts-requesting-changes Integer

      Specifies the total snapshots requesting changes.

    • total-snapshots-unreviewed Integer

      Gives the total number of snapshots that are unreviewed

    • total-comparisons Integer

      Number of total comparisons.

    • total-comparisons-finished Integer

      Number of total comparisons finished processing.

    • total-comparisons-diff Integer

      Specifies the total comparisons where diffs have been identified.

    • total-open-commits Integer

      Number of total commits.

    • failed-snapshots-count Integer

      Number of failed snapshots.

    • failed-reason String

      Status of the failure.

    • failure-details String

      Details of the failure.

    • parallel-nonce String

      It is a unique ID.

    • parallel-total-shards String

      The number of parallel nodes being ran.

    • finished-at Integer

      Time stamp when the build has finished running.

    • finalized-at Integer

      Time when users CI completed the job.

    • approved-at Integer

      Time stamp when the build was approved.

    • created-at Integer

      Time stamp when the build was started.

    • updated-at Integer

      Time stamp when the build was last updated.

  • 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

    • project Object

      Specifies the details of the project and API Endpoint to fetch.

    • commit Object

      Specifies the details of the commits and API Endpoint to fetch.

    • repo Object

      Specifies the details of the repo and API Endpoint to fetch.

    • base-build Object

      Specifies the details of the base-build and API Endpoint to fetch.

    • base-build-strategy Object

      Specifies the details of the base-build-strategy.

    • approved-by Object

      Details of the approver.

    • snapshots Object

      Endpoints to access the snapshots.

    • comparisons Object

      Endpoints to access the comparisons(equals to screenshots).

    • browsers Object

      Specifies the details of the browsers.

    • removed-snapshots Object

      Endpoints to access the removed-snapshots.

    • failed-snapshots Object

      Endpoints to access the removed-snapshots.

    • missing-resources Object

      Endpoints to access the missing-resources.

  • meta Object

    Details of test session.

    ▶ SHOW VALUES

    • finalize-link String

      API Endpoint to finalize the build.

    • approve-link String

      API Endpoint to approve the build.

Get build details

GET https://percy.io/api/v1/builds/{build_id}

Retrieves the build details for the given build_id.

Request parameters

Curl Request

curl --request GET \
     --url 'https://percy.io/api/v1/builds/{build_id}'
     --header 'Authorization: Token token=auto_xxxxxx'

  • build_id* string

    ID of the desired build.

Response attributes 200 OK JSON

Response

{
  "data": {
    "type": "builds",
    "id": "3xxxxxx",
    "attributes": {
      "branch": "unknown-branch",
      "type": "automate",
      "build-number": 9,
      "partial": false,
      "web-url": "https://percy.io/9xxxxxxxx/test-auto/builds/3xxxxxx",
      "commit-html-url": null,
      "branch-html-url": null,
      "pull-request-html-url": null,
      "state": "finished",
      "review-state": "unreviewed",
      "review-state-reason": "unreviewed_snapshots",
      "is-pull-request": false,
      "pull-request-number": null,
      "pull-request-title": null,
      "user-agent": "Percy/v1 @percy/client/1.27.1 @percy/cli-exec/1.27.1 percy-selenium-python/2.0.0-alpha.0 (node/v20.5.1; selenium/4.8.3; python/3.11.5)",
      "total-snapshots": 1,
      "total-snapshots-requesting-changes": 0,
      "total-snapshots-unreviewed": 1,
      "total-comparisons": 1,
      "total-comparisons-finished": 1,
      "total-comparisons-diff": 1,
      "total-open-comments": 0,
      "failed-snapshots-count": 0,
      "failure-reason": null,
      "failure-details": null,
      "parallel-nonce": null,
      "parallel-total-shards": null,
      "finished-at": "2023-10-03T10:17:51.000Z",
      "finalized-at": "2023-10-03T10:17:50.000Z",
      "approved-at": null,
      "created-at": "2023-10-03T10:17:20.000Z",
      "updated-at": "2023-10-03T10:17:51.000Z"
    },
    "links": {
      "self": "/api/v1/builds/3xxxxxx"
    },
    "relationships": {
      "project": {
        "links": {
          "self": "/api/v1/builds/3xxxxxx/relationships/project",
          "related": "/api/v1/builds/3xxxxxx/project"
        },
        "data": {
          "type": "projects",
          "id": "4xxxxxx"
        }
      },
      "commit": {
        "links": {
          "self": "/api/v1/builds/3xxxxxx/relationships/commit",
          "related": "/api/v1/builds/3xxxxxx/commit"
        },
        "data": null
      },
      "repo": {
        "links": {
          "self": "/api/v1/builds/3xxxxxx/relationships/repo",
          "related": "/api/v1/builds/3xxxxxx/repo"
        },
        "data": null
      },
      "base-build": {
        "links": {
          "self": "/api/v1/builds/3xxxxxx/relationships/base-build",
          "related": "/api/v1/builds/3xxxxxx/base-build"
        },
        "data": null
      },
      "base-build-strategy": {
        "data": {
          "type": "base-build-strategies",
          "id": "7xxxxxx"
        }
      },
      "approved-by": {
        "links": {
          "self": "/api/v1/builds/3xxxxxx/relationships/approved-by",
          "related": "/api/v1/builds/3xxxxxx/approved-by"
        },
        "data": null
      },
      "snapshots": {
        "links": {
          "self": "/api/v1/builds/3xxxxxx/relationships/snapshots",
          "related": "/api/v1/builds/3xxxxxx/snapshots"
        }
      },
      "comparisons": {
        "links": {
          "self": "/api/v1/builds/3xxxxxx/relationships/comparisons",
          "related": "/api/v1/builds/3xxxxxx/comparisons"
        }
      },
      "browsers": {
        "links": {
          "self": "/api/v1/builds/3xxxxxx/relationships/browsers",
          "related": "/api/v1/builds/3xxxxxx/browsers"
        },
        "data": []
      },
      "removed-snapshots": {
        "links": {
          "self": "/api/v1/builds/3xxxxxx/relationships/removed-snapshots",
          "related": "/api/v1/builds/3xxxxxx/removed-snapshots"
        }
      },
      "failed-snapshots": {
        "links": {
          "self": "/api/v1/builds/3xxxxxx/relationships/failed-snapshots",
          "related": "/api/v1/builds/3xxxxxx/failed-snapshots"
        }
      },
      "missing-resources": {
        "links": {
          "self": "/api/v1/builds/3xxxxxx/relationships/missing-resources",
          "related": "/api/v1/builds/3xxxxxx/missing-resources"
        }
      }
    },
    "meta": {
      "finalize-link": "/api/v1/builds/3xxxxxx/finalize",
      "approve-link": "/api/v1/builds/3xxxxxx/approve"
    }
  },
  "included": [
    {
      "type": "projects",
      "id": "4xxxxxx",
      "attributes": {
        "name": "test-auto",
        "slug": "test-auto",
        "type": "automate",
        "full-slug": "9xxxxxxxx/test-auto",
        "is-enabled": true,
        "diff-base": "automatic",
        "auto-approve-branch-filter": "",
        "approval-required-branch-filter": "*",
        "default-base-branch": "master",
        "updated-at": "2023-10-03T10:17:51.000Z",
        "publicly-readable": false,
        "is-demo": false,
        "is-auto-browser-upgrade": true,
        "wait-for-base-build": false,
        "current-period-usage": 5,
        "screenshot-limit": null,
        "workflow": "git",
        "diff-sensitivity-level": 2
      },
      "links": {
        "self": "/api/v1/projects/9xxxxxxxx/test-auto"
      },
      "relationships": {
        "organization": {
          "links": {
            "related": "/api/v1/projects/9xxxxxxxx/test-auto/organization"
          },
          "data": {
            "type": "organizations",
            "id": "30412"
          }
        },
        "repo": {
          "links": {
            "related": "/api/v1/projects/9xxxxxxxx/test-auto/repo"
          },
          "data": null
        },
        "builds": {
          "links": {
            "related": "/api/v1/builds?project_id=4xxxxxx"
          }
        },
        "tokens": {
          "links": {
            "related": "/api/v1/projects/9xxxxxxxx/test-auto/tokens"
          }
        },
        "browser-targets": {
          "data": []
        },
        "project-browser-targets": {
          "data": []
        },
        "webhook-configs": {
          "data": []
        }
      }
    },
    {
      "type": "base-build-strategies",
      "id": "7xxxxxx",
      "attributes": {
        "ideal-branch-strategy": "latest_approved",
        "actual-branch-strategy": "no_base",
        "ideal-commit-strategy": "latest_approved",
        "actual-commit-strategy": "no_base",
        "pull-request-skipped-reason": "no_pull_request_number",
        "merge-base-skipped-reason": "unknown_branch",
        "target-commit-reason": null,
        "target-commit-skipped-reason": null,
        "target-branch": null,
        "target-commit-sha": null
      }
    }
  ]
}

  • attributes Object

    Details of test session.

    ▶ SHOW VALUES

    • branch String

      Specifies the Git branch name.

    • type String

      Specifies if the project is a Web or App project.

    • build-number Integer

      Specifies the build number.

    • partial Boolean

      Specifies if its a partial build.

    • web-url String

      Path to the build URL.

    • commit-html-url String

      Path to the commit URL.

    • branch-html-url String

      Path to the branch URL.

    • pull-request-html-url String

      Path to the pull-request URL.

    • state String

      Specifies if the build is finished.

    • review-state String

      Specifies build review state changes_requested or approved. Expected values are unreviewed, approved, changes_requested, merged, rejected.

    • review-state-reason String

      Specifies the reason for changes requested or approved. 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.

    • is-pull-request Boolean

      Specifies if there is a pull-request.

    • pull-request-number String

      Lists the pull request number.

    • pull-request-title String

      Specifies the pull request title.

    • user-agent String

      Percy CLI user agent.

    • total-snapshots Integer

      Specifies the total snapshot count.

    • total-snapshosts-requesting-changes Integer

      Specifies the total snapshots requesting changes.

    • total-snapshots-unreviewed Integer

      Gives the total number of snapshots that are unreviewed

    • total-comparisons Integer

      Number of total comparisons.

    • total-comparisons-finished Integer

      Number of total comparisons finished processing.

    • total-comparisons-diff Integer

      Specifies the total comparisons where diffs have been identified.

    • total-open-commits Integer

      Number of total commits.

    • failed-snapshots-count Integer

      Number of failed snapshots.

    • failed-reason String

      Status of the failure.

    • failure-details String

      Details of the failure.

    • parallel-nonce String

      Unique ID.

    • parallel-total-shards Integer

      The number of parallel nodes being ran.

    • finished-at Integer

      Time stamp when the build has finished running.

    • finalized-at Integer

      Time when users CI completed the job.

    • approved-at Integer

      Time stamp when the build was approved.

    • created-at Integer

      Time stamp when the build was started.

    • updated-at Integer

      Time stamp when the build was last updated.

  • 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

    • project Object

      Specifies the details of the project and API Endpoint to fetch.

    • commit Object

      Specifies the details of the commits and API Endpoint to fetch.

    • repo Object

      Specifies the details of the repo and API Endpoint to fetch.

    • base-build Object

      Specifies the details of the base-build and API Endpoint to fetch.

    • base-build-strategy Object

      Specifies the details of the base-build-strategy.

    • approved-by Object

      Details of the approver.

    • snapshots Object

      Endpoints to access the snapshots.

    • comparisons Object

      Endpoints to access the comparisons(equals to screenshots).

    • browsers Object

      Specifies the details of the browsers.

    • removed-snapshots Object

      Endpoints to access the removed-snapshots.

    • failed-snapshots Object

      Endpoints to access the removed-snapshots.

    • missing-resources Object

      Endpoints to access the missing-resources.

  • meta Object

    Details of test session.

    ▶ SHOW VALUES

    • finalize-link String

      API Endpoint to finalize the build.

    • approve-link String

      API Endpoint to approve the build.

Approve build

POST https://percy.io/api/v1/reviews

Approves the build for the given build_id.

Note:

Request parameters

Curl Request

curl --location 'https://percy.io/api/v1/reviews' \
--header 'Content-Type: application/json' \
--header "Authorization: Basic $(echo -n '<username>:<accesskey>' | base64)" \
--data '{
    "data": {
        "attributes": {
            "action": "approve"
        },
        "relationships": {
            "build": {
                "data": {
                    "type": "builds",
                    "id": "41xxxxxx"
                }
            }
        },
        "type": "reviews"
    }
}'

  • build_id* string

    ID of the desired build.

Response attributes 200 OK JSON

Response

{
    "data": {
        "type": "reviews",
        "id": "45xxxxxx",
        "attributes": {
            "action": "approve",
            "snapshot-ids": [],
            "review-state": "approved",
            "action-performed-by": {
                "user_email": "abc.si@browserstack.com",
                "user_name": "User name"
            }
        },
        "links": {
            "self": "/api/v1/reviews/45xxxxxx"
        },
        "relationships": {
            "build": {
                "links": {
                    "related": "/api/v1/builds/45xxxxxx"
                }
            }
        }
    }
}

  • attributes Object

    Details of test session.

    ▶ SHOW VALUES

    • action String

      The type of review action performed (e.g., approve, unapprove, reject).

    • snapshot-ids Array

      List of snapshot IDs affected by the review action.

    • review-state String

      The resulting review status of the build.

    • action-performed-by Object

      The user details (email and name) of the person who performed the action.

  • links Object

    Details of test session.

    ▶ SHOW VALUES

    • self Object

      Time stamp when the build was last updated.

  • relationships Object

    Details of test session.

    ▶ SHOW VALUES

    • build.links.related Object

      The API endpoint for the build associated with this review.

Unapprove build

POST https://percy.io/api/v1/reviews

Unapproves the build for the given build_id.

Request parameters

Curl Request

curl --location 'https://percy.io/api/v1/reviews' \
--header 'Content-Type: application/json' \
--header "Authorization: Basic $(echo -n '<username>:<accesskey>' | base64)" \
--data '{
    "data": {
        "attributes": {
            "action": "unapprove"
        },
        "relationships": {
            "build": {
                "data": {
                    "type": "builds",
                    "id": "41xxxxxx"
                }
            }
        },
        "type": "reviews"
    }
}'

  • build_id* string

    ID of the desired build.

Response attributes 200 OK JSON

Response

{
    "data": {
        "type": "reviews",
        "id": "45xxxxxx",
        "attributes": {
            "action": "unapprove",
            "snapshot-ids": [
                223xxxxxxx,
                223xxxxxxx,
                223xxxxxxx,
                223xxxxxxx,
                223xxxxxxx,
                223xxxxxxx,
                223xxxxxxx,
                223xxxxxxx,
                223xxxxxxx,
                223xxxxxxx,
                223xxxxxxx,
                223xxxxxxx
            ],
            "review-state": "unreviewed",
            "action-performed-by": {
                "user_email": "abc.si@browserstack.com",
                "user_name": "User name"
            }
        },
        "links": {
            "self": "/api/v1/reviews/45xxxxxx"
        },
        "relationships": {
            "build": {
                "links": {
                    "related": "/api/v1/builds/45xxxxxx"
                }
            }
        }
    }
}

  • attributes Object

    Details of test session.

    ▶ SHOW VALUES

    • action String

      The type of review action performed (e.g., approve, unapprove, reject).

    • snapshot-ids Array

      List of snapshot IDs affected by the review action.

    • review-state String

      The resulting review status of the build.

    • action-performed-by Object

      The user details (email and name) of the person who performed the action.

  • links Object

    Details of test session.

    ▶ SHOW VALUES

    • self Object

      Time stamp when the build was last updated.

  • relationships Object

    Details of test session.

    ▶ SHOW VALUES

    • build.links.related Object

      The API endpoint for the build associated with this review.

Reject build

POST https://percy.io/api/v1/reviews

Rejects the build for the given build_id.

Request parameters

Curl Request

curl --location 'https://percy.io/api/v1/reviews' \
--header 'Content-Type: application/json' \
--header "Authorization: Basic $(echo -n '<username>:<accesskey>' | base64)" \
--data '{
    "data": {
        "attributes": {
            "action": "reject"
        },
        "relationships": {
            "build": {
                "data": {
                    "type": "builds",
                    "id": "41xxxxxx"
                }
            }
        },
        "type": "reviews"
    }
}'

  • build_id* string

    ID of the desired build.

Response attributes 200 OK JSON

Response

{
    "data": {
        "type": "reviews",
        "id": "45xxxxxx",
        "attributes": {
            "action": "reject",
            "snapshot-ids": [
                223xxxxxxx,
                223xxxxxxx,
                223xxxxxxx,
                223xxxxxxx,
                223xxxxxxx,
                223xxxxxxx,
                223xxxxxxx,
                223xxxxxxx,
                223xxxxxxx,
                223xxxxxxx,
                223xxxxxxx,
                223xxxxxxx
            ],
            "review-state": "rejected",
            "action-performed-by": {
                "user_email": "abc.si@browserstack.com",
                "user_name": "User name"
            }
        },
        "links": {
            "self": "/api/v1/reviews/45xxxxx"
        },
        "relationships": {
            "build": {
                "links": {
                    "related": "/api/v1/builds/41xxxxxxx"
                }
            }
        }
    }
}

  • attributes Object

    Details of test session.

    ▶ SHOW VALUES

    • action String

      The type of review action performed (“reject” in this case).

    • snapshot-ids Array

      List of snapshot IDs affected by the review action.

    • review-state String

      The resulting state of the build after the action (“rejected” here).

    • action-performed-by Object

      The user details (email and name) of the person who performed the action.

  • links Object

    Details of test session.

    ▶ SHOW VALUES

    • self String

      API endpoint for the current review resource.

Delete build

POST https://percy.io/api/v1/builds/build_id/delete

Deletes the build for the given build_id.

Request parameters

Curl Request

curl --location 'https://percy.io/api/v1/builds/<build_id>/delete' \
--header 'Content-Type: application/json' \
--header "Authorization: Basic $(echo -n '<username>:<accesskey>' | base64)"

  • build_id* string

    ID of the desired build.

Response attributes 200 OK JSON

Response

{
'success':true,
'action-performed-by': {
  'user_email': 'abc.si@browserstack.com',
  'user_name': 'User name',
}
}

  • success Boolean

    Indicates whether the action was completed successfully.

  • action-performed-by Object

    Contains the email and name of the user who performed the action.

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