---
title: "Calculate histograms on continuous integration runs, such as GitHub Actions, Jenkins, Circle, etc."
method: POST
path: "/histograms/code_checks"
tags: ["histograms", "default"]
---

# Calculate histograms on continuous integration runs, such as GitHub Actions, Jenkins, Circle, etc.

`POST /histograms/code_checks`

## Request

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

## Request body

- CodeCheckHistogramsRequest: Request of `/histograms/code_checks`.
  - `for` ForSetCodeChecks[], required: Sets of developers and repositories for which to calculate the histograms. The aggregation is `AND` between repositories and developers. The aggregation is `OR` inside both repositories and developers.
    - `repositories` RepositoryID[], required: Set of repositories. An empty list raises a bad response 400. Duplicates are automatically ignored.
    - `repogroups` array[]: Lists of indexes in `repositories` or `developers` that define independent groups that must be processed individually. The groups may have intersections.
      - integer[]
    - `pushers` 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`).
    - `pusher_groups` CommitPushers[]: Check runs must be triggered by commits authored by these people. We aggregate by each group so that you can request metrics of several teams at once. We treat `pushers` as another group, if specified.
      - 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.
    - `lines` integer[]: Split by changed number of lines (inserted + removed) in pull requests.
  - `histograms` CodeCheckHistogramDefinition[], required: Histogram parameters for each wanted topic.
    - `metric` 'chk-suites-count' | 'chk-suites-in-prs-count' | 'chk-successful-suites-count' | 'chk-failed-suites-count' | 'chk-cancelled-suites-count' | 'chk-success-ratio' | 'chk-suite-time' | 'chk-robust-suite-time' | 'chk-suites-per-pr' | 'chk-suite-time-per-pr' | 'chk-prs-with-checks-count' | 'chk-flaky-commit-checks-count' | 'chk-prs-merged-with-failed-checks-count' | 'chk-prs-merged-with-failed-checks-ratio' | 'chk-concurrency-max' | 'chk-concurrency' | 'chk-elapsed-time-per-concurrency' | 'chk-suite-occupancy' | 'chk-suite-critical-occupancy' | 'chk-suite-imbalance', required: The mentioned terms such as "check suite" and "check run" belong to [the official documentation on GitHub](https://docs.github.com/en/rest/guides/getting-started-with-the-checks-api#about-check-runs). * `chk-suites-count` - number of executed check suites. * `chk-suites-in-prs-count` - number of executed check suites in pull requests. * `chk-successful-suites-count` - number of successfully executed check suites. * `chk-failed-suites-count` - number of failed check suites. * `chk-cancelled-suites-count` - number of cancelled check suites. * `chk-success-ratio` - `chk-successful-suites-count` divided by `chk-suites-count`. * `chk-suite-time` - average check suite execution time. * `chk-robust-suite-time` - average check suite execution time, alternative algorithm. We consider each suite size group separately, fill missing daily values by averaging the neighbors, and then take the average of group averages. * `chk-suites-per-pr` - average number of times check suites executed in a pull request. * `chk-suite-time-per-pr` - average check suite execution time by pull request. The difference with `chk-suite-time` is that we don't consider checks triggered by direct pushes, e.g. by merge commits. * `chk-prs-with-checks-count` - number of PRs that triggered at least one check suite. * `chk-flaky-commit-checks-count` - number of check suites triggered by the same commit but having different outcomes - both successful and failed. * `chk-prs-merged-with-failed-checks-count` - how many PRs were merged despite failing checks. * `chk-prs-merged-with-failed-checks-ratio` - ratio of PRs merged with failing checks to all merged PRs with checks. * `chk-concurrency-max` - maximum number of check runs of the same type executing in parallel. We consider check runs executing in parallel if their time intervals overlap ≥ 50%. * `chk-concurrency` - average number of check runs of the same type executing in parallel; we choose the check run type that corresponds to the maximum concurrency for each day. We consider check runs executing in parallel if their time intervals overlap ≥ 50%. * `chk-elapsed-time-per-concurrency` - cumulative time spent on each concurrency level across check runs. Only allowed for histograms. * `chk-suite-occupancy` - average ratio between summed time of check runs in a check suite and the product of the number of check runs with the maximum check run time in that check suite. 1 means ideal resource utilization, down to 0 for absolute inefficiency. For example, there are one slow check run that executes in 10x seconds, and N fast check runs that execute in x seconds, in the same check suite. The metric value will be (10x + Nx) / (10*(N+1)*x) → 0.1 if N → +∞. * `chk-suite-critical-occupancy` - `chk-suite-occupancy` calculated for critical check runs only. A critical check run is a check run of type that at least once dominated the check suite execution time on the time interval. This is the measure of check suite "trebble" when there are several slowest check runs that elapse time with some standard deviation. * `chk-suite-imbalance` - average difference between the time of the slowest and the second slowest check runs in a check suite. High values signal unbalanced jobs and CI/CD inefficiency.
    - `scale` 'linear' | 'log': Histogram's X axis scale.
    - `bins` integer: Number of bars in the histogram. 0 or null means automatic.
    - `ticks` union[]: Alternatively to `bins` and `scale`, set the X axis bar borders manually. Only one of two may be specified. The ticks are automatically prepended the distribution minimum and appended the distribution maximum.
      - union
        - number
        - string: Time duration value.
  - `date_from` string, date, required: Date from when to start measuring the distribution.
  - `date_to` string, date, required: Date until which to measure the distribution.
  - `timezone` integer: Local time zone offset in minutes, used to adjust `date_from` and `date_to`.
  - `quantiles` number[]: Cut the distributions at certain quantiles. The default values are [0, 1] which means no cutting.
  - `split_by_check_runs` boolean: Calculate histograms separately for each number of check runs in suite.
  - `account` integer, required: Session account ID.

## Response `200`

Calculated histograms.

- CalculatedCodeCheckHistogram[]: Response from `/histograms/code_checks`.
  - `for` ForSetCodeChecks, required: Filters for `/metrics/code_checks` and `/histograms/code_checks`. Achieve the best performance by packing all your filters in a single `ForSetCodeChecks` instead of sending multiple `ForSetCodeChecks`-s. For example, use `repogroups` and `pushers` to request separate metrics for several repository sets and teams.
    - `repositories` RepositoryID[], required: Set of repositories. An empty list raises a bad response 400. Duplicates are automatically ignored.
    - `repogroups` array[]: Lists of indexes in `repositories` or `developers` that define independent groups that must be processed individually. The groups may have intersections.
      - integer[]
    - `pushers` 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`).
    - `pusher_groups` CommitPushers[]: Check runs must be triggered by commits authored by these people. We aggregate by each group so that you can request metrics of several teams at once. We treat `pushers` as another group, if specified.
      - 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.
    - `lines` integer[]: Split by changed number of lines (inserted + removed) in pull requests.
  - `metric` 'chk-suites-count' | 'chk-suites-in-prs-count' | 'chk-successful-suites-count' | 'chk-failed-suites-count' | 'chk-cancelled-suites-count' | 'chk-success-ratio' | 'chk-suite-time' | 'chk-robust-suite-time' | 'chk-suites-per-pr' | 'chk-suite-time-per-pr' | 'chk-prs-with-checks-count' | 'chk-flaky-commit-checks-count' | 'chk-prs-merged-with-failed-checks-count' | 'chk-prs-merged-with-failed-checks-ratio' | 'chk-concurrency-max' | 'chk-concurrency' | 'chk-elapsed-time-per-concurrency' | 'chk-suite-occupancy' | 'chk-suite-critical-occupancy' | 'chk-suite-imbalance', required: The mentioned terms such as "check suite" and "check run" belong to [the official documentation on GitHub](https://docs.github.com/en/rest/guides/getting-started-with-the-checks-api#about-check-runs). * `chk-suites-count` - number of executed check suites. * `chk-suites-in-prs-count` - number of executed check suites in pull requests. * `chk-successful-suites-count` - number of successfully executed check suites. * `chk-failed-suites-count` - number of failed check suites. * `chk-cancelled-suites-count` - number of cancelled check suites. * `chk-success-ratio` - `chk-successful-suites-count` divided by `chk-suites-count`. * `chk-suite-time` - average check suite execution time. * `chk-robust-suite-time` - average check suite execution time, alternative algorithm. We consider each suite size group separately, fill missing daily values by averaging the neighbors, and then take the average of group averages. * `chk-suites-per-pr` - average number of times check suites executed in a pull request. * `chk-suite-time-per-pr` - average check suite execution time by pull request. The difference with `chk-suite-time` is that we don't consider checks triggered by direct pushes, e.g. by merge commits. * `chk-prs-with-checks-count` - number of PRs that triggered at least one check suite. * `chk-flaky-commit-checks-count` - number of check suites triggered by the same commit but having different outcomes - both successful and failed. * `chk-prs-merged-with-failed-checks-count` - how many PRs were merged despite failing checks. * `chk-prs-merged-with-failed-checks-ratio` - ratio of PRs merged with failing checks to all merged PRs with checks. * `chk-concurrency-max` - maximum number of check runs of the same type executing in parallel. We consider check runs executing in parallel if their time intervals overlap ≥ 50%. * `chk-concurrency` - average number of check runs of the same type executing in parallel; we choose the check run type that corresponds to the maximum concurrency for each day. We consider check runs executing in parallel if their time intervals overlap ≥ 50%. * `chk-elapsed-time-per-concurrency` - cumulative time spent on each concurrency level across check runs. Only allowed for histograms. * `chk-suite-occupancy` - average ratio between summed time of check runs in a check suite and the product of the number of check runs with the maximum check run time in that check suite. 1 means ideal resource utilization, down to 0 for absolute inefficiency. For example, there are one slow check run that executes in 10x seconds, and N fast check runs that execute in x seconds, in the same check suite. The metric value will be (10x + Nx) / (10*(N+1)*x) → 0.1 if N → +∞. * `chk-suite-critical-occupancy` - `chk-suite-occupancy` calculated for critical check runs only. A critical check run is a check run of type that at least once dominated the check suite execution time on the time interval. This is the measure of check suite "trebble" when there are several slowest check runs that elapse time with some standard deviation. * `chk-suite-imbalance` - average difference between the time of the slowest and the second slowest check runs in a check suite. High values signal unbalanced jobs and CI/CD inefficiency.
  - `scale` 'linear' | 'log', required: X axis scale: linear or logarithmic.
  - `ticks` union[], required: Series of horizontal bar borders aka X axis. Their count is `len(y) + 1` because there are `N` intervals between `(N + 1)` ticks.
    - union
      - number
      - string: Time duration value.
  - `frequencies` integer[], required: Series of histogram bar heights aka Y axis.
  - `interquartile` Interquartile, required: Middle 50% range.
    - `left` union, required
      - number
      - string: Time duration value.
    - `right` union, required
      - number
      - string: Time duration value.

## Other responses

- `400`: The request is invalid.
- `403`: The user is forbidden to access the specified repositories on behalf of the specified account.
- `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`: 2 info
  - added the new optional request property `for/items/jira/allOf[#/components/schemas/JIRAFilter]/status_categories`
  - added the optional property `items/for/jira/allOf[#/components/schemas/JIRAFilter]/status_categories` to the response with the `200` status

[Operation history](https://skmtc.dev/athenian/apis/title/changes/histograms/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)