# List check runs for a Git reference

From **GitHub v3 REST API**.

`GET /repos/{owner}/{repo}/commits/{ref}/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.

Lists check runs for a commit ref. The `ref` can be a SHA, branch name, or a tag name. GitHub Apps must have the `checks:read` permission on a private repository or pull access to a public repository to get check runs. OAuth Apps and authenticated users must have the `repo` scope to get check runs in a private repository.

## Parameters

### `owner`

- Location: path
- Required: true
- Type: `string`

### `repo`

- Location: path
- Required: true
- Type: `string`

### `ref`

- Location: path
- Required: true
- Type: `string`

ref parameter

### `check_name`

- Location: query
- Required: false
- Type: `string`

Returns check runs with the specified `name`.

### `status`

- Location: query
- Required: false
- Type: `string`
- Allowed values: `"queued"`, `"in_progress"`, `"completed"`

Returns check runs with the specified `status`. Can be one of `queued`, `in_progress`, or `completed`.

### `filter`

- Location: query
- Required: false
- Type: `string`
- Default: `latest`
- Allowed values: `"latest"`, `"all"`

Filters check runs by their `completed_at` timestamp. Can be one of `latest` (returning the most recent check runs) or `all`.

### `per_page`

- Location: query
- Required: false
- Type: `integer`
- Default: `30`

Results per page (max 100)

### `page`

- Location: query
- Required: false
- Type: `integer`
- Default: `1`

Page number of the results to fetch.

### `app_id`

- Location: query
- Required: false
- Type: `integer`

## Responses

### `200`

Response

#### Headers

##### `Link`

- Type: `string`

- Example: `<https://api.github.com/resource?page=2>; rel="next", <https://api.github.com/resource?page=5>; rel="last"`

### `application/json`

- Type: `object`

```json
{
  "check_runs": [
    {
      "app": {
        "created_at": "2017-07-08T16:18:44-04:00",
        "description": "",
        "events": [
          "push",
          "pull_request"
        ],
        "external_url": "https://example.com",
        "html_url": "https://github.com/apps/octoapp",
        "id": 1,
        "name": "Octocat App",
        "node_id": "MDExOkludGVncmF0aW9uMQ==",
        "owner": {
          "avatar_url": "https://github.com/images/error/octocat_happy.gif",
          "events_url": "https://api.github.com/orgs/github/events",
          "followers_url": "https://api.github.com/users/octocat/followers",
          "following_url": "https://api.github.com/users/octocat/following{/other_user}",
          "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
          "gravatar_id": "",
          "html_url": "https://github.com/octocat",
          "id": 1,
          "login": "github",
          "node_id": "MDEyOk9yZ2FuaXphdGlvbjE=",
          "organizations_url": "https://api.github.com/users/octocat/orgs",
          "received_events_url": "https://api.github.com/users/octocat/received_events",
          "repos_url": "https://api.github.com/orgs/github/repos",
          "site_admin": true,
          "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
          "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
          "type": "User",
          "url": "https://api.github.com/orgs/github"
        },
        "permissions": {
          "contents": "read",
          "issues": "write",
          "metadata": "read",
          "single_file": "write"
        },
        "slug": "octoapp",
        "updated_at": "2017-07-08T16:18:44-04:00"
      },
      "check_suite": {
        "id": 5
      },
      "completed_at": "2018-05-04T01:14:52Z",
      "conclusion": "neutral",
      "details_url": "https://example.com",
      "external_id": "",
      "head_sha": "ce587453ced02b1526dfb4cb910479d431683101",
      "html_url": "https://github.com/github/hello-world/runs/4",
      "id": 4,
      "name": "mighty_readme",
      "node_id": "MDg6Q2hlY2tSdW40",
      "output": {
        "annotations_count": 2,
        "annotations_url": "https://api.github.com/repos/github/hello-world/check-runs/4/annotations",
        "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.",
        "title": "Mighty Readme report"
      },
      "pull_requests": [
        {
          "base": {
            "ref": "master",
            "repo": {
              "id": 526,
              "name": "hello-world",
              "url": "https://api.github.com/repos/github/hello-world"
            },
            "sha": "e7fdf7640066d71ad16a86fbcbb9c6a10a18af4f"
          },
          "head": {
            "ref": "say-hello",
            "repo": {
              "id": 526,
              "name": "hello-world",
              "url": "https://api.github.com/repos/github/hello-world"
            },
            "sha": "3dca65fa3e8d4b3da3f3d056c59aee1c50f41390"
          },
          "id": 1934,
          "number": 3956,
          "url": "https://api.github.com/repos/github/hello-world/pulls/1"
        }
      ],
      "started_at": "2018-05-04T01:14:52Z",
      "status": "completed",
      "url": "https://api.github.com/repos/github/hello-world/check-runs/4"
    }
  ],
  "total_count": 1
}
```

```json
{"properties":{"check_runs":{"items":{"$ref":"#/components/schemas/check-run"},"type":"array"},"total_count":{"type":"integer"}},"required":["total_count","check_runs"],"type":"object"}
```

## Request examples

### cURL

```shell
curl --request GET \
  --url {protocol}://{hostname}/api/v3/repos/{owner}/{repo}/commits/{ref}/check-runs
```