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

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

`POST /metrics/code_checks`

## Request

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

## Request body

- CodeCheckMetricsRequest: Request for calculating metrics on top of code check runs (CI) data.
  - `for` ForSetCodeChecks[], required: Sets of developers and repositories for which to calculate the metrics. 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.
  - `metrics` CodeCheckMetricID[], required: Requested metric identifiers.
  - `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`.
  - `granularities` Granularity[], required: The splits of the specified time range.
  - `quantiles` number[]: Cut the distributions at certain quantiles. The default values are [0, 1] which means no cutting.
  - `account` integer, required: Session account ID.
  - `split_by_check_runs` boolean: Calculate metrics separately for each number of check runs in suite.

## Response `200`

Calculated metrics.

- CalculatedCodeCheckMetrics: Response from `/metrics/code_checks`. The dates start from `date_from` and end earlier or equal to `date_to`. The order of the items is *not* guaranteed to match any expectations.
  - `calculated` CalculatedCodeCheckMetricsItem[], required: Values of the requested metrics through time.
    - `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.
    - `granularity` string: How often the metrics are reported. The value must satisfy the following regular expression: /^all|(([1-9]\d* )?(aligned )?(day|week|month|year))$/. "all" produces a single interval [`date_from`, `date_to`]. "aligned week/month/year" produces intervals cut by calendar week/month/year borders, for example, when `date_from` is `2020-01-15` and `date_to` is `2020-03-10`, the intervals will be `2020-01-15` - `2020-02-01` - `2020-03-01` - `2020-03-10`.
    - `check_runs` integer: We calculated metrics for check suites with this number of runs. Not null only if the user specified `split_by_check_runs = true`.
    - `suites_ratio` number, float: Number of check suites with `check_runs` number of check runs divided by the overall number of check suites. Not null only if the user specified `split_by_check_runs = true`.
    - `values` CalculatedLinearMetricValues[], required: The sequence steps from `date_from` till `date_to` by `granularity`.
      - `date` string, date, required: Where you should relate the metric value to on the time axis.
      - `values` union[], required: Calculated metric values in the same order as `metrics`.
        - union
          - number
          - string: Time duration value.
          - object
      - `confidence_mins` union[]: Confidence interval @ p=0.8, minimum. The same order as `metrics`. It is optional because there can be exact metrics like "count open PRs per month".
        - union
          - number, nullable
          - string: Time duration value.
      - `confidence_maxs` union[]: Confidence interval @ p=0.8, maximum. The same order as `metrics`. It is optional because there can be exact metrics like "count open PRs per month".
        - union
          - number, nullable
          - string: Time duration value.
      - `confidence_scores` integer[]: Confidence score from 0 (random guess) to 100 (very confident). The same order as `metrics`. May be `null` for exact metrics.
  - `metrics` CodeCheckMetricID[], required: Repeats `CodeCheckMetricsRequest.metrics`.
  - `date_from` string, date, required: Repeats `CodeCheckMetricsRequest.date_from`.
  - `date_to` string, date, required: Repeats `CodeCheckMetricsRequest.date_to`.
  - `timezone` integer: Local time zone offset in minutes, used to adjust `date_from` and `date_to`.
  - `granularities` Granularity[], required: The splits of the specified time range.
  - `quantiles` number[]: Cut the distributions at certain quantiles. The default values are [0, 1] which means no cutting.
  - `split_by_check_runs` boolean: Repeats `CodeCheckMetricsRequest.split_by_check_runs`.

## 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 `calculated/items/for/jira/allOf[#/components/schemas/JIRAFilter]/status_categories` to the response with the `200` status
- **2023-02-23** `9e4a34d4017e`: 1 breaking
  - the `granularities` request property's minItems was increased to `1`

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