---
title: "Calculate metrics on deployments submitted by `/events/deployments`."
method: POST
path: "/metrics/deployments"
tags: ["metrics", "default"]
---

# Calculate metrics on deployments submitted by \`/events/deployments\`.

`POST /metrics/deployments`

## Request

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

## Request body

- DeploymentMetricsRequest: Request body of `/metrics/deployments`, the deployments selector.
  - `for` ForSetDeployments[], required: Sets of filters for which to calculate the metrics. The aggregation is `AND` between individual properties like `repositories` or `with`. The aggregation is `OR` inside each property.
    - `repositories` RepositoryID[]: 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[]
    - `with` DeploymentWith: Deployment contribution roles. The aggregation is `OR` everywhere. It is possible to mention whole teams using the syntax `{id}` where `id` is a team identifier (see `/teams`).
      - `pr_author` DeveloperID[]: Authors of deployed pull requests.
      - `commit_author` DeveloperID[]: Authors of deployed commits.
      - `releaser` DeveloperID[]: Deployed release publishers.
    - `withgroups` DeploymentWith[]: Alternative to `with` - calculate metrics for distinct filters separately.
      - `pr_author` DeveloperID[]: Authors of deployed pull requests.
      - `commit_author` DeveloperID[]: Authors of deployed commits.
      - `releaser` DeveloperID[]: Deployed release publishers.
    - `pr_labels_include` string[]: At least one of these labels must be present in at least one deployed PR.
    - `pr_labels_exclude` string[]: None of these labels must be present in each deployed PR.
    - `jira` JIRAFilter: 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.
    - `with_labels` object: Deployments should contain at least one of the specified label values. `null` matches any label value and effectively checks the label existence.
    - `without_labels` object: Deployments may not contain the specified label values. `null` matches any label value and effectively ensures that the label does not exist.
    - `environments` string[]: List of environments for which to calculate the metrics. We calculate the metrics for each environment independently.
    - `envgroups` array[]: List of environment groups for which to calculate the metrics.
      - string[]
  - `metrics` DeploymentMetricID[], 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.

## Response `200`

Calculated metrics.

- CalculatedDeploymentMetric[]: Response from `/metrics/deployments`, metrics calculated for each selected deployments group. The order of the items is *not* guaranteed to match any expectations.
  - `for` ForSetDeployments, required: Filters for `/metrics/deployments`. Nothing is strictly required. Achieve the best performance by packing all your filters in a single `ForSetDeployments` instead of sending multiple `ForSetDeployments`-s. For example, use `repogroups` and `withgroups` to request separate metrics for several repository sets and teams.
    - `repositories` RepositoryID[]: 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[]
    - `with` DeploymentWith: Deployment contribution roles. The aggregation is `OR` everywhere. It is possible to mention whole teams using the syntax `{id}` where `id` is a team identifier (see `/teams`).
      - `pr_author` DeveloperID[]: Authors of deployed pull requests.
      - `commit_author` DeveloperID[]: Authors of deployed commits.
      - `releaser` DeveloperID[]: Deployed release publishers.
    - `withgroups` DeploymentWith[]: Alternative to `with` - calculate metrics for distinct filters separately.
      - `pr_author` DeveloperID[]: Authors of deployed pull requests.
      - `commit_author` DeveloperID[]: Authors of deployed commits.
      - `releaser` DeveloperID[]: Deployed release publishers.
    - `pr_labels_include` string[]: At least one of these labels must be present in at least one deployed PR.
    - `pr_labels_exclude` string[]: None of these labels must be present in each deployed PR.
    - `jira` JIRAFilter: 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.
    - `with_labels` object: Deployments should contain at least one of the specified label values. `null` matches any label value and effectively checks the label existence.
    - `without_labels` object: Deployments may not contain the specified label values. `null` matches any label value and effectively ensures that the label does not exist.
    - `environments` string[]: List of environments for which to calculate the metrics. We calculate the metrics for each environment independently.
    - `envgroups` array[]: List of environment groups for which to calculate the metrics.
      - string[]
  - `metrics` DeploymentMetricID[], required
  - `granularity` string, required: 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`.
  - `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.

## 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-04-17** `8d74770e2ef9`: 2 warning, 2 info
  - added the new `dep-change-failure-count` enum value to the `items/metrics/items/` response property for the response status `200`
  - added the new `dep-change-failure-ratio` enum value to the `items/metrics/items/` response property for the response status `200`
  - added the new `dep-change-failure-count` enum value to the request property `metrics/items/`
  - added the new `dep-change-failure-ratio` enum value to the request property `metrics/items/`
- **2023-03-03** `f9fdd9fbfc25`: 2 info
  - added the new optional request property `for/items/jira/status_categories`
  - added the optional property `items/for/jira/status_categories` to the response with the `200` status
- **2023-02-23** `a04e310a6f1a`: 1 breaking
  - the `granularities` request property's minItems was increased to `1`
- **2022-11-16** `fcf829c0439e`: 2 info
  - added the new optional request property `for/items/jira/priorities`
  - added the optional property `items/for/jira/priorities` to the response with the `200` status
- **2022-11-16** `cb74c2b3ef0d`: 2 warning
  - removed the request property `for/items/jira/priorities`
  - removed the optional property `items/for/jira/priorities` from the response with the `200` status

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