Does the GitHub API provide a way to check if a branch is up-to-date?

Question

In GitHub, in the branch protection settings, you can require branches to be up to date before merging (this is possible both for both GitHub Enterprise and for public repos in free GitHub):

Then on a PR, if the branch is not up to date with the base branch, and this base branch is protected in this way, you will see the following in the UI:

Using the GitHub API, is there any way to detect if a branch is out of date relative to a base branch, or to detect if a PR is such that the head branch is out-of-date with the base branch?

I am working with a GitHub Enterprise instance, so unique features of the GitHub Enterprise API can be included in any answers.

I already looked through the GitHub Enterprise API docs in some detail, and I didn't see a way to detect this, but it is very possible I missed something.

Answer 1

Unless I am mistaken, this can be done by using the compare commits API endpoint.

You can make a request to this API endpoint, and then check the behind_by part of the JSON response. If this value is 0, the head branch is up-to-date relative to the base branch; else, the head branch is not up-to-date relative to the base branch.