Anatomy of the Checks API

Checks API extends the build and deploy process once your deployment is ready. Each check behaves like a webhook that triggers specific events, such as deployment.created, deployment.ready, and deployment.succeeded. The test are verified before domains are assigned.

To learn more, see the Supported Webhooks Events docs.

The workflow for registering and running a check is as follows:

1. A check is created after the deployment.created event
2. When the deployment.ready event triggers, the check updates its status to running
3. When the check is finished, the status updates to completed

If a check is "rerequestable", your integration users get an option to rerequest and rerun the failing checks.

Depending on the type, checks can block the domain assignment stage of deployments.

• Blocking Checks: Prevents a successful deployment and returns a conclusion with a state value of canceled or failed. For example, a Core Check returning a 404 error results in a failed conclusion for a deployment
• Non-blocking Checks: Return test results with a successful deployment regardless of the conclusion

A blocking check with a failed state is configured by the developer (and not the integration).

Checks are always associated with a specific deployment that is tested and validated.

The check gets a stale status if there is no status update for more than one hour (status = registered). The same applies if the check is running (status = running) for more than five minutes.

The output property can store any data like Web Vitals and Virtual Experience Score. It is defined under a metrics field:

Each of these keys has the following properties:

metrics makes Web Vitals visible on checks. It is defined inside output as follows:

{
  "path": "/",
  "output": {
    "metrics": {
        "FCP": {
          "value": 1200,
          "previousValue": 1400,
          "source": "web-vitals"
        }
        "LCP": {
          "value": 1200,
          "previousValue": 1400,
          "source": "web-vitals"
        },
        "CLS": {
          "value": 1200,
          "previousValue": 1400,
          "source": "web-vitals"
        },
        "TBT": {
          "value": 1200,
          "previousValue": 1400,
          "source": "web-vitals"
        }
      }
    }
  }
}

A check can be "rerequested" using the deployment.check-rerequested webhook. Add the rerequestable attribute, and you can rerequest failed checks.

A rerequested check triggers thedeployment.check-rerequested webhook. It updates the check status to running and resets the conclusion, detailsUrl, externalId, and output fields.

You can "Skip" to stop and ignore check results without affecting the alias assignment. You cannot skip active checks. They continue running until built successfully, and assign domains as the last step.

For "Running Checks", only the Automatic Deployment URL is available. Automatic Branch URL and Custom Domains will apply once the checks finish.

Checks may take different times to run. Each integrator determines the running order of the checks. While Vercel REST API determines the order of check results.

When Checks API begins running on your deployment, the status is set to running. Once it gets a conclusion, the status updates to completed. This results in a successful deployment.

However, your deployment will fail if the conclusion updates to one of the following values: