Text of docs.github.com › en › rest › checks › runs as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

REST API endpoints for check runs - GitHub Docs

Skip to main content Skip to content Collapse sidebar Expand sidebar The REST API is now versioned. For more information, see " About API versioning ." REST API endpoints for check runs Use the REST API to manage check runs. Note Write permission for the REST API to interact with checks is only available to GitHub Apps. OAuth apps and authenticated users can view check runs and check suites, but they are not able to create them.

If you aren't building a GitHub App, you might be interested in using the REST API to interact with commit statuses . Create a check run Creates a new check run for a specific commit in a repository. To create a check run, you must use a GitHub App. OAuth apps and authenticated users are not able to create a check suite. In a check suite, GitHub limits the number of check runs with the same name to 1000. Once these check runs exceed 1000, GitHub will start to automatically delete older check runs.

Note The Checks API only looks for pushes in the repository where the check suite or check run were created. Pushes to a branch in a forked repository are not detected and return an empty pull_requests array. Fine-grained access tokens for "Create a check run" This endpoint works with the following fine-grained token types : GitHub App user access tokens GitHub App installation access tokens The fine-grained token must have the following permission set: "Checks" repository permissions (write) Parameters for "Create a check run" Headers Name, Type, Description accept string Setting to application/vnd.github+json is recommended.

Path parameters Name, Type, Description owner string Required The account owner of the repository. The name is not case sensitive. repo string Required The name of the repository without the .git extension. The name is not case sensitive. Body parameters Name, Type, Description name string Required The name of the check. For example, "code-coverage". head_sha string Required The SHA of the commit. details_url string The URL of the integrator's site that has the full details of the check.

If the integrator does not provide this, then the homepage of the GitHub app is used. external_id string A reference for the run on the integrator's system. status string The current status of the check run. Only GitHub Actions can set a status of waiting , pending , or requested . Default : queued Can be one of : queued , in_progress , completed , waiting , requested , pending started_at string The time that the check run began.

This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ . conclusion string Required if you provide completed_at or a status of completed . The final conclusion of the check. Note: Providing conclusion will automatically set the status parameter to completed . You cannot change a check run conclusion to stale , only GitHub can set this. Can be one of : action_required , cancelled , failure , neutral , success , skipped , stale , timed_out completed_at string The time the check completed.

This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ . output object Check runs can accept a variety of data in the output object, including a title and summary and can optionally provide descriptive details about the run. Properties of output Name, Type, Description title string Required The title of the check run. summary string Required The summary of the check run. This parameter supports Markdown. Maximum length : 65535 characters. text string The details of the check run.

This parameter supports Markdown. Maximum length : 65535 characters. annotations array of objects Adds information from your analysis to specific lines of code. Annotations are visible on GitHub in the Checks and Files changed tab of the pull request. The Checks API limits the number of annotations to a maximum of 50 per API request. To create more than 50 annotations, you have to make multiple requests to the Update a check run endpoint.

Each time you update the check run, annotations are appended to the list of annotations that already exist for the check run. GitHub Actions are limited to 10 warning annotations and 10 error annotations per step. For details about how you can view annotations on GitHub, see " About status checks ". Properties of annotations Name, Type, Description path string Required The path of the file to add an annotation to. For example, assets/css/main.css . start_line integer Required The start line of the annotation.

Line numbers start at 1. end_line integer Required The end line of the annotation. start_column integer The start column of the annotation. Annotations only support start_column and end_column on the same line. Omit this parameter if start_line and end_line have different values. Column numbers start at 1. end_column integer The end column of the annotation. Annotations only support start_column and end_column on the same line.

Omit this parameter if start_line and end_line have different values. annotation_level string Required The level of the annotation. Can be one of : notice , warning , failure message string Required A short description of the feedback for these lines of code. The maximum size is 64 KB. title string The title that represents the annotation. The maximum size is 255 characters. raw_details string Details about this annotation.

The maximum size is 64 KB. images array of objects Adds images to the output displayed in the GitHub pull request UI. Properties of images Name, Type, Description alt string Required The alternative text for the image. image_url string Required The full URL of the image. caption string A short image description. actions array of objects Displays a button on GitHub that can be clicked to alert your app to do additional tasks.

For example, a code linting app can display a button that automatically fixes detected errors. The button created in this object is displayed after the check run completes. When a user clicks the button, GitHub sends the check_run.requested_action webhook to your app. Each action includes a label , identifier and description . A maximum of three actions are accepted. To learn more about check runs and requested actions, see " Check runs and requested actions ." Properties of actions Name, Type, Description label string Required The text to be displayed on a button in the web UI.

The maximum size is 20 characters. description string Required A short explanation of what this action would do. The maximum size is 40 characters. identifier string Required A reference for the action on the integrator's system. The maximum size is 20 characters. HTTP response status codes for "Create a check run" Status code Description 201 Created Code samples for "Create a check run" Request examples Select the example type post /repos /{owner} /{repo} /check-runs Copy to clipboard curl request example curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2026-03-10" \ https://api.github.com/repos/OWNER/REPO/check-runs \ -d '{"name":"mighty_readme","head_sha":"ce587453ced02b1526dfb4cb910479d431683101","status":"in_progress","external_id":"42","started_at":"2018-05-04T01:14:52Z","output":{"title":"Mighty Readme report","summary":"","text":""}}' Response for in_progress conclusion Status: 201 { "id": 4, "head_sha": "ce587453ced02b1526dfb4cb910479d431683101", "node_id": "MDg6Q2hlY2tSdW40", "external_id": "42", "url": "https://api.github.com/repos/github/hello-world/check-runs/4", "html_url": "https://github.com/github/hello-world/runs/4", "details_url": "https://example.com", "status": "in_progress", "conclusion": null, "started_at": "2018-05-04T01:14:52Z", "completed_at": null, "output": { "title": "Mighty Readme report", "summary": "There are 0 failures, 2 warnings, and 1 notice.", "text": "You may have some misspelled words on lines 2 and 4.

You also may want to add a section in your README about how to install your app.", "annotations_count": 2, "annotations_url": "https:

The rest of this page is on the live site.