---
title: "Find code check runs that match the specified query. [What a code check run is exactly.](https://docs.github.com/en/rest/guides/getting-started-with-the-checks-api#about-check-runs)"
method: POST
path: "/filter/code_checks"
tags: ["filter", "default"]
---

# Find code check runs that match the specified query. \[What a code check run is exactly.\](https://docs.github.com/en/rest/guides/getting-started-with-the-checks-api#about-check-runs)

`POST /filter/code_checks`

## Request

- Base URL: `{{ server_url }}/v1`
- URL: `{{ server_url }}/v1/filter/code_checks`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/athenian/apis/title/docs/filter/code_checks/post.ts> (a function with typed inputs; its response is checked against the schema)

## Request body

- FilterCodeChecksRequest: Request body of `/filter/code_checks`.
  - `in` RepositoryID[], required: Set of repositories. An empty list raises a bad response 400. Duplicates are automatically ignored.
  - `triggered_by` DeveloperID[]: Check runs must be triggered by commits pushed by these people. When it is impossible to determine who pushed, e.g. in legacy API based checks, they are committers. It is possible to mention whole teams using the syntax `{id}` where `id` is a team identifier (see `/teams`).
  - `labels_include` string[]: At least one of these labels must be present in the checked PRs.
  - `labels_exclude` string[]: None of these labels must be present in each checked PR.
  - `jira` object: Filters related to JIRA traits. The aggregation between each filter type is *AND*.
    - `epics` string[]: JIRA issues must be included in the epics from the list.
    - `labels_include` string[]: Only issues having at least one label from the list will be included Several labels may be concatenated by a comma `,` so that all of them are required.
    - `labels_exclude` string[]: Issues having one label from the list will be excluded.
    - `issue_types` string[]: Issues must have one of the given types, e.g. Bug, Task, Design Document, etc.
    - `priorities` string[]: Issues must have a priority from the given list.
    - `projects` string[]: Issues must be contained in a project in the given project keys list.
    - `status_categories` JIRAStatusCategory[]: The JIRA issues must have a status belonging to one of these categories.
    - `unmapped` boolean: Select PRs that are not mapped to any JIRA issue. May not be specified with anything else.
  - `date_from` string, date, required: Date from when to start measuring the metrics.
  - `date_to` string, date, required: Date until which to measure the metrics.
  - `timezone` integer: Local time zone offset in minutes, used to adjust `date_from` and `date_to`.
  - `account` integer, required: Session account ID.
  - `quantiles` number[]: Cut the distributions at certain quantiles. The default values are [0, 1] which means no cutting.

## Response `200`

Code check runs that satisfy the specified filters.

- FilteredCodeCheckRuns: Response from `/filter/code_checks`, found code check runs ordered by repository name and then by title. Note: we always consider the completed run executions only.
  - `timeline` string[], required: Sequence of dates from `date_from` till `date_to`. We choose the adaptive intervals by applying these rules on `(date_to - date_from)`: - Less than 5 weeks: daily. - Less than 5 months: weekly (*not aligned*). - Aligned monthly.
  - `items` FilteredCodeCheckRun[], required: Found check runs and their stats.
    - `title` string, required: Unique name of the check run.
    - `repository` string, required: Repository name which uniquely identifies any repository in any service provider. The format matches the repository URL without the protocol part. No ".git" should be appended. We support a special syntax for repository sets: "{reposet id}" adds all the repositories from the given set.
    - `last_execution_time` string, date-time, required: Timestamp of when the check run launched the latest.
    - `last_execution_url` string, url: Link to the check run that launched the latest.
    - `total_stats` object, required: Gathered statistics about a group of check runs.
      - `count` integer, required: Number of executions with respect to `date_from` and `date_to`.
      - `successes` integer, required: Number of successful executions with respect to `date_from` and `date_to`.
      - `critical` boolean, required: This code check dominated the overall check suite execution time at least once.
      - `mean_execution_time` union, required
        - string, nullable: Average elapsed execution time.
        - string: Time duration value.
      - `stddev_execution_time` union, required
        - string, nullable: Standard deviation of the execution time. Higher values for a `critical` code check indicate an optimization opportunity: it is better to have a stable execution time with the same average.
        - string: Time duration value.
      - `median_execution_time` union, required
        - string, nullable: Median elapsed execution time.
        - string: Time duration value.
      - `skips` integer, required: Number of times this check run was skipped.
      - `flaky_count` integer, required: Number of times this check run appeared flaky: it both failed and succeeded for the same commit.
      - `count_timeline` integer[], required: Number of executions through time. The dates sequence is `FilteredCodeCheckRuns.timeline`.
      - `successes_timeline` integer[], required: Number of successful executions through time. The dates sequence is `FilteredCodeCheckRuns.timeline`.
      - `mean_execution_time_timeline` TimeDuration[], required: Average elapsed execution time through time. The dates sequence is `FilteredCodeCheckRuns.timeline`.
      - `median_execution_time_timeline` TimeDuration[], required: Median elapsed execution time through time. The dates sequence is `FilteredCodeCheckRuns.timeline`.
    - `prs_stats` object, required: Gathered statistics about a group of check runs.
      - `count` integer, required: Number of executions with respect to `date_from` and `date_to`.
      - `successes` integer, required: Number of successful executions with respect to `date_from` and `date_to`.
      - `critical` boolean, required: This code check dominated the overall check suite execution time at least once.
      - `mean_execution_time` union, required
        - string, nullable: Average elapsed execution time.
        - string: Time duration value.
      - `stddev_execution_time` union, required
        - string, nullable: Standard deviation of the execution time. Higher values for a `critical` code check indicate an optimization opportunity: it is better to have a stable execution time with the same average.
        - string: Time duration value.
      - `median_execution_time` union, required
        - string, nullable: Median elapsed execution time.
        - string: Time duration value.
      - `skips` integer, required: Number of times this check run was skipped.
      - `flaky_count` integer, required: Number of times this check run appeared flaky: it both failed and succeeded for the same commit.
      - `count_timeline` integer[], required: Number of executions through time. The dates sequence is `FilteredCodeCheckRuns.timeline`.
      - `successes_timeline` integer[], required: Number of successful executions through time. The dates sequence is `FilteredCodeCheckRuns.timeline`.
      - `mean_execution_time_timeline` TimeDuration[], required: Average elapsed execution time through time. The dates sequence is `FilteredCodeCheckRuns.timeline`.
      - `median_execution_time_timeline` TimeDuration[], required: Median elapsed execution time through time. The dates sequence is `FilteredCodeCheckRuns.timeline`.
    - `size_groups` integer[], required: Check suite sizes this check run belongs to.

## Other responses

- `400`: The request is invalid.
- `403`: Calling user is not allowed to access the specified repositories.
- `404`: The specified account does not exist or the user is not a member.
- `422`: The account's installation has not finished yet.

## Changes

- **2023-03-03** `f9fdd9fbfc25`: 1 info
  - added the new optional request property `jira/allOf[#/components/schemas/JIRAFilter]/status_categories`

[Operation history](https://skmtc.dev/athenian/apis/title/changes/filter/code_checks/post.md)

---

[API](https://skmtc.dev/athenian/apis/title.md) - [All operations](https://skmtc.dev/athenian/apis/title/llms.txt) - [OpenAPI document](https://skmtc.dev/athenian/apis/title/revisions/110c9f7cffdd?raw)