---
title: "Calculate metrics over JIRA issue activities."
method: POST
path: "/metrics/jira"
tags: ["metrics", "default"]
---

# Calculate metrics over JIRA issue activities.

`POST /metrics/jira`

## Request

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

## Request body

- JIRAMetricsRequest: Request body of `/metrics/jira`.
  - `account` integer, required: Session account ID.
  - `date_from` string, date, required: Issues must be resolved after this date.
  - `date_to` string, date, required: Issues must be created before this date.
  - `for` JIRAFilter[]: Calculate metrics separately for each JIRA Filter in the list. Not compatible with other jira filters in the request: `priorities`, `types`, `labels_include`, `labels_exclude`, `epics`, `projects`.
    - `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.
  - `timezone` integer: Local time zone offset in minutes, used to adjust `date_from` and `date_to`.
  - `priorities` string[]: Selected issue priorities.
  - `types` string[]: Selected issue types.
  - `labels_include` string[]: JIRA issues must contain at least one label from the list. Several labels may be concatenated by a comma `,` so that all of them are required.
  - `labels_exclude` string[]: JIRA issues may not contain labels from this list.
  - `exclude_inactive` boolean, required: Value indicating whether issues with the last update older than `date_from` should be ignored. If `date_from` and `date_to` are `null`, does nothing.
  - `epics` string[]: JIRA issues must be attached to any of the epic IDs from this list.
  - `with` JIRAFilterWith[]: Groups of issue participants. The metrics will be calculated for each group.
    - `assignees` string[]: Selected issue assignee users. `null` means unassigned.
    - `reporters` string[]: Selected issue reporter users.
    - `commenters` string[]: Selected issue commenter users.
  - `projects` string[]: Issues must belong to these JIRA projects.
  - `metrics` JIRAMetricID[], required: List of measured metrics.
  - `quantiles` number[]: Cut the distributions at certain quantiles. The default values are [0, 1] which means no cutting.
  - `granularities` Granularity[], required: The splits of the specified time range.
  - `group_by_jira_label` boolean: Value indicating whether the metrics should be grouped by assigned JIRA issue label.

## Response `200`

Calculated metrics.

- CalculatedJIRAMetricValues[]: Response from `/metrics/jira`. The order of the items is *not* guaranteed to match any expectations.
  - `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`.
  - `for` 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.
  - `jira_label` string: Title of the assigned JIRA label, if `group_by_jira_label` was previously set to `true`. If is missing and `group_by_jira_label` was set to `true` then the metrics are calculated for issues without labels.
  - `with` JIRAFilterWith: Group of JIRA issue participant names split by role.
    - `assignees` string[]: Selected issue assignee users. `null` means unassigned.
    - `reporters` string[]: Selected issue reporter users.
    - `commenters` string[]: Selected issue commenter users.
  - `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.
- `424`: One or more logical repositories miss the release settings.

## Changes

- **2023-04-07** `63ec2eb2e4b3`: 1 info
  - added the new `jira-acknowledge-time-below-threshold-ratio` enum value to the request property `metrics/items/`
- **2023-03-03** `f9fdd9fbfc25`: 2 info
  - added the new optional request property `for/items/status_categories`
  - added the optional property `items/for/status_categories` to the response with the `200` status
- **2023-02-23** `56f35ea63f32`: 1 breaking
  - the `granularities` request property's minItems was increased to `1`
- **2023-02-13** `976a8c4017cf`: 1 info
  - added the optional property `items/for` to the response with the `200` status
- **2023-02-13** `63a42cdcb699`: 1 info
  - added the new optional request property `for`

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