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 , , and . 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:
- A check is created after the event
- When the event triggers, the check updates its to
- When the check is finished, the updates to
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 with a value of or . For example, a Core Check returning a error results in a for a deployment
- Non-blocking Checks: Return test results with a successful deployment regardless of the
A blocking check with a state is configured by the developer (and not the integration).
Checks are always associated with a specific deployment that is tested and validated.
| Attributes | Format | Purpose |
|---|---|---|
| Boolean | Tells Vercel if this check needs to block the deployment | |
| String | Name of the check | |
| String (optional) | URL to display in the Vercel dashboard | |
| String (optional) | ID used for external use | |
| String (optional) | Path of the page that is being checked | |
| Boolean (optional) | Tells Vercel if the check can rerun. Users can trigger a webhook, through a button on the deployment page | |
| String (optional) | The result of a running check. For blocking checks the values can be , , , , . and | |
| String (optional) | Tells Vercel the status of the check with values: and | |
| Object (optional) | Details about the result of the check. Vercel uses this data to display actionable information for developers. This helps them debug failed checks |
The check gets a status if there is no status update for more than one hour (). The same applies if the check is running () for more than five minutes.
| Response | Format | Purpose |
|---|---|---|
| String | The status of the check. It expects specific values like or | |
| String | Tells the current state of the connection | |
| Number | Timestamp (in milliseconds) of when the configuration was connected | |
| String | Name of the integrator performing the check |
| Status | Outcome |
|---|---|
| Success | |
| One of the provided values in the request body is invalid, OR one of the provided values in the request query is invalid | |
| The provided token is not from an OAuth2 client OR you do not have permission to access this resource OR the API token doesn't have permission to perform the request | |
| The check was not found OR the deployment was not found | |
| The output provided is too large |
The property can store any data like Web Vitals and Virtual Experience Score. It is defined under a field:
| Key | Type | Description |
|---|---|---|
| Map | The Total Blocking Time, measured by the check | |
| Map | The Largest Contentful Paint, measured by the check | |
| Map | The First Contentful Paint, measured by the check | |
| Map | The Cumulative Layout Shift, measured by the check | |
| Map | The overall Virtual Experience Score measured by the check |
Each of these keys has the following properties:
| Key | Type | Description |
|---|---|---|
| Float | The value measured for a particular metric, in milliseconds. For this value is the percentage between 0 and 1 | |
| Float | A previous value for comparison purposes | |
| Enum |
makes Web Vitals visible on checks. It is defined inside as follows:
All fields are required except previousValue. If
previousValue is present, the delta will be shown.
A check can be "rerequested" using the webhook. Add the attribute, and you can rerequest failed checks.
A rerequested check triggers the webhook. It updates the check to and resets the , , , and 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 is set to . Once it gets a , the updates to . This results in a successful deployment.
However, your deployment will fail if the updates to one of the following values:
| Conclusion | |
|---|---|
| Yes | |
| Yes | |
| No | |
| No | |
| No |
Was this helpful?