Skip to main content
No Result Found

Visual Scanner

Trigger a scan manually using the Visual scanner API. Execute Visual scanner builds on-demand, allowing immediate checks and faster response times to visual discrepancies.

Trigger Visual Scan

POST https://percy.io/api/v1/visual-scanner-builds

Triggers visual scan from the project corresponding to the given PERCY_TOKEN.

Request parameters

No parameter required.

Request

export PERCY_TOKEN=YOUR_PERCY_TOKEN
curl -X POST \
     -H "Authorization: Token token=$PERCY_TOKEN"  https://percy.io/api/v1/visual-scanner-builds

Response attributes 200 OK JSON

Response

 {
  "data": {
    "type": "builds",
    "id": "10xxxxx",
    "attributes": {
      "branch": "visual_scanning",
      "type": "visual_monitoring_web",
      "build-number": 3,
      "partial": false,
      "web-url": "https://percy.io/my-slug/my-project/builds/10xxxxx",
      "commit-html-url": null,
      "branch-html-url": null,
      "pull-request-html-url": null,
      "state": "processing",
      "review-state": null,
      "review-state-reason": null,
      "is-pull-request": false,
      "pull-request-number": null,
      "pull-request-title": null,
      "user-agent": "Percy::VisualMonitoringBuildService",
      "total-test-cases": null,
      "total-test-cases-unreviewed": null,
      "total-test-cases-failed": null,
      "total-snapshots": 1,
      "total-snapshots-requesting-changes": 0,
      "total-snapshots-unreviewed": null,
      "total-comparisons": 1,
      "total-comparisons-finished": 0,
      "total-comparisons-diff": null,
      "total-open-comments": 0,
      "failed-snapshots-count": 0,
      "failure-reason": null,
      "failure-details": null,
      "parallel-nonce": null,
      "parallel-total-shards": null,
      "finished-at": null,
      "finalized-at": "2024-06-05T09:07:42.000Z",
      "approved-at": null,
      "created-at": "2024-06-05T09:07:42.000Z",
      "updated-at": "2024-06-05T09:07:42.000Z",
      "prod-build": false,
      "vm-staging-base-url": null
    },
    "links": {
      "self": "/api/v1/builds/1xxxxx"
    },
    "relationships": {
      "project": {
        "links": {
          "self": "/api/v1/builds/1xxxxx/relationships/project",
          "related": "/api/v1/builds/1xxxxx/project"
        },
        "data": {
          "type": "projects",
          "id": "56xxxxx"
        }
      },
      "commit": {
        "links": {
          "self": "/api/v1/builds/1xxxxx/relationships/commit",
          "related": "/api/v1/builds/1xxxxx/commit"
        },
        "data": null
      },
      "repo": {
        "links": {
          "self": "/api/v1/builds/1xxxxx/relationships/repo",
          "related": "/api/v1/builds/1xxxxx/repo"
        },
        "data": null
      },
      "base-build": {
        "links": {
          "self": "/api/v1/builds/1xxxxx/relationships/base-build",
          "related": "/api/v1/builds/1xxxxx/base-build"
        },
        "data": {
          "type": "builds",
          "id": "1xxxxx"
        }
      },
      "base-build-strategy": {},
      "approved-by": {
        "links": {
          "self": "/api/v1/builds/1xxxxx/relationships/approved-by",
          "related": "/api/v1/builds/1xxxxx/approved-by"
        },
        "data": null
      },
      "snapshots": {
        "links": {
          "self": "/api/v1/builds/1xxxxx/relationships/snapshots",
          "related": "/api/v1/builds/1xxxxx/snapshots"
        }
      },
      "comparisons": {
        "links": {
          "self": "/api/v1/builds/1xxxxx/relationships/comparisons",
          "related": "/api/v1/builds/1xxxxx/comparisons"
        }
      },
      "browsers": {
        "links": {
          "self": "/api/v1/builds/1xxxxx/relationships/browsers",
          "related": "/api/v1/builds/1xxxxx/browsers"
        },
        "data": [
          {
            "type": "browsers",
            "id": "00"
          }
        ]
      },
      "removed-snapshots": {
        "links": {
          "self": "/api/v1/builds/1xxxxx/relationships/removed-snapshots",
          "related": "/api/v1/builds/1xxxxx/removed-snapshots"
        }
      },
      "failed-snapshots": {
        "links": {
          "self": "/api/v1/builds/1xxxxx/relationships/failed-snapshots",
          "related": "/api/v1/builds/1xxxxx/failed-snapshots"
        }
      },
      "missing-resources": {
        "links": {
          "self": "/api/v1/builds/1xxxxx/relationships/missing-resources",
          "related": "/api/v1/builds/1xxxxx/missing-resources"
        }
      }
    },
    "meta": {
      "finalize-link": "/api/v1/builds/1xxxxx/finalize",
      "approve-link": "/api/v1/builds/1xxxxx/approve"
    }
  },
  "included": [
    {
      "type": "projects",
      "id": "56xxxxx",
      "attributes": {
        "name": "my-project",
        "slug": "my-slug",
        "type": "visual_monitoring_web",
        "full-slug": "my-project/my-slug",
        "is-enabled": true,
        "diff-base": "automatic",
        "auto-approve-branch-filter": "",
        "approval-required-branch-filter": null,
        "default-base-branch": "master",
        "updated-at": "2024-06-05T08:19:28.000Z",
        "publicly-readable": false,
        "is-demo": false,
        "is-auto-browser-upgrade": true,
        "wait-for-base-build": false,
        "current-period-usage": 3,
        "screenshot-limit": null,
        "workflow": "git",
        "intelli-ignore-enabled": true,
        "intelli-ignore-diff-ignore-percentage": 0.2,
        "default-ignore-diff-ignore-percentage": 0.2,
        "diff-sensitivity-level": 2,
        "visual-monitoring-urls": [
          "https://www.example.com"
        ],
        "schedule": false,
        "next-schedule-time": null,
        "vm-staging-base-url": null,
        "latest-build-stat": {
          "state": "finished",
          "build_id": 1xxxxx,
          "review_state": "unreviewed",
          "failure_reason": null,
          "review_state_reason": "unreviewed_snapshots",
          "total_snapshots_with_changes": 1
        },
        "vm-last-build-baseline": false,
        "created-at": "2024-06-04T13:15:32.000Z",
        "delay-seconds": "5.0",
        "vm-diff-ignore-enabled": false,
        "vm-diff-ignore-percentage": null,
        "auth-type": "form",
        "auth-config-name": "test",
        "auth-params": {
          "password": "********",
          "username": "username",
          "login_url": "https://practice.expandtesting.com/login",
          "password_selector": "#password",
          "username_selector": "#username",
          "submit_button_selector": "/html/body/main/div/div/div[2]/div/div/div/form/button"
        },
        "sitemap-ids": [],
        "cron": "0 */6 * * *",
        "schedule-start": "2024-06-04T13:15:27.733Z",
        "schedule-end": "2044-01-01T00:00:00.000Z"
      },
      "links": {
        "self": "/api/v1/projects/my-slug/my-project"
      },
      "relationships": {
        "organization": {
          "links": {
            "related": "/api/v1/projects/my-slug/my-project/organization"
          },
          "data": {
            "type": "organizations",
            "id": "1xx"
          }
        },
        "repo": {
          "links": {
            "related": "/api/v1/projects/my-slug/my-project/repo"
          },
          "data": null
        },
        "builds": {
          "links": {
            "related": "/api/v1/builds?project_id=101"
          }
        },
        "tokens": {
          "links": {
            "related": "/api/v1/projects/my-slug/my-project/tokens"
          }
        },
        "browser-targets": {
          "data": [
            {
              "type": "browser-targets",
              "id": "6xx"
            }
          ]
        },
        "project-browser-targets": {
          "data": [
            {
              "type": "project-browser-targets",
              "id": "7xxxxxx"
            }
          ]
        },
        "webhook-configs": {
          "data": []
        }
      }
    },
    {
      "type": "browsers",
      "id": "5x",
      "attributes": {
        "version": "122.0"
      },
      "links": {
        "self": "/api/v1/browsers/5x"
      },
      "relationships": {
        "browser-family": {
          "data": {
            "type": "browser-families",
            "id": "x"
          }
        }
      }
    },
    {
      "type": "browser-families",
      "id": "x",
      "attributes": {
        "name": "Firefox",
        "slug": "firefox"
      }
    },
    {
      "type": "builds",
      "id": "1xxxxx",
      "attributes": {
        "branch": "visual_scanning",
        "type": "visual_monitoring_web",
        "build-number": 2,
        "partial": false,
        "web-url": "https://percy.io/my-slug/my-project/builds/1000001",
        "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::VisualMonitoringBuildService",
        "total-test-cases": 0,
        "total-test-cases-unreviewed": 0,
        "total-test-cases-failed": 0,
        "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": "2024-06-05T08:19:28.000Z",
        "finalized-at": "2024-06-05T08:18:42.000Z",
        "approved-at": null,
        "created-at": "2024-06-05T08:18:42.000Z",
        "updated-at": "2024-06-05T08:19:28.000Z",
        "prod-build": false,
        "vm-staging-base-url": null
      },
      "links": {
        "self": "/api/v1/builds/3xxxxxxx"
      },
      "relationships": {
        "project": {
          "links": {
            "self": "/api/v1/builds/1xxxxx/relationships/project",
            "related": "/api/v1/builds/1xxxxx/project"
          },
          "data": {
            "type": "projects",
            "id": "5xxxxx"
          }
        },
        "commit": {
          "links": {
            "self": "/api/v1/builds/1xxxxx/relationships/commit",
            "related": "/api/v1/builds/1xxxxx/commit"
          },
          "data": null
        },
        "repo": {
          "links": {
            "self": "/api/v1/builds/1xxxxx/relationships/repo",
            "related": "/api/v1/builds/1xxxxx/repo"
          },
          "data": null
        },
        "base-build": {
          "links": {
            "self": "/api/v1/builds/1xxxxx/relationships/base-build",
            "related": "/api/v1/builds/1xxxxx/base-build"
          },
          "data": {
            "type": "builds",
            "id": "1xxxxx"
          }
        },
        "base-build-strategy": {},
        "approved-by": {
          "links": {
            "self": "/api/v1/builds/1xxxxx/relationships/approved-by",
            "related": "/api/v1/builds/1xxxxx/approved-by"
          },
          "data": null
        },
        "snapshots": {
          "links": {
            "self": "/api/v1/builds/1xxxxx/relationships/snapshots",
            "related": "/api/v1/builds/1xxxxx/snapshots"
          }
        },
        "comparisons": {
          "links": {
            "self": "/api/v1/builds/1xxxxx/relationships/comparisons",
            "related": "/api/v1/builds/1xxxxx/comparisons"
          }
        },
        "browsers": {
          "links": {
            "self": "/api/v1/builds/1xxxxx/relationships/browsers",
            "related": "/api/v1/builds/1xxxxx/browsers"
          },
          "data": [
            {
              "type": "browsers",
              "id": "5x"
            }
          ]
        },
        "removed-snapshots": {
          "links": {
            "self": "/api/v1/builds/1xxxxx/relationships/removed-snapshots",
            "related": "/api/v1/builds/1xxxxx/removed-snapshots"
          }
        },
        "failed-snapshots": {
          "links": {
            "self": "/api/v1/builds/1xxxxx/relationships/failed-snapshots",
            "related": "/api/v1/builds/1xxxxx/failed-snapshots"
          }
        },
        "missing-resources": {
          "links": {
            "self": "/api/v1/builds/1xxxxx/relationships/missing-resources",
            "related": "/api/v1/builds/1xxxxx/missing-resources"
          }
        }
      },
      "meta": {
        "finalize-link": "/api/v1/builds/1xxxxx/finalize",
        "approve-link": "/api/v1/builds/1xxxxx/approve"
      }
    }
  ]
}
  • attributes Object

    Details of visual scan.

    SHOW VALUES
    • build_id String

      Specifies the build ID. Use this ID to fetch the build details using the build details API.

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