--- title: "Calculate metrics over developer activities." method: POST path: "/metrics/developers" tags: ["metrics", "default"] --- # Calculate metrics over developer activities. `POST /metrics/developers` ## Request - Base URL: `{{ server_url }}/v1` - URL: `{{ server_url }}/v1/metrics/developers` - Auth: one of: - HTTP bearer - API key in header `X-API-Key` - TypeScript: (a function with typed inputs; its response is checked against the schema) ## Request body - DeveloperMetricsRequest: Request for calculating metrics on top of developer activities. - `for` ForSetDevelopers[], required: Sets of developers and repositories to calculate the metrics for. - `repositories` RepositoryID[], required: Set of repositories. An empty list raises a bad response 400. Duplicates are automatically ignored. - `developers` DeveloperID[], required: A set of developers. An empty list disables the filter and includes everybody. 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[] - `aggregate_devgroups` array[]: Lists of indexes in `repositories` or `developers` that define independent groups that must be processed individually. The groups may have intersections. - integer[] - `labels_include` string[]: PRs must be labeled with at least one name from this list so that the related metrics include them. - `labels_exclude` string[]: PRs must not be labeled with any name from this list so that the related metrics exclude them. - `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. - `metrics` DeveloperMetricID[], 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`. - `account` integer, required: Session account ID. - `granularities` Granularity[], required: The splits of the specified time range. ## Response `200` Calculated metrics. - CalculatedDeveloperMetrics: Response of `/metrics/developers`. 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` CalculatedDeveloperMetricsItem[], required: Values of the requested metrics by developer through time. - `for` ForSetDevelopers, required: Filter for `/metrics/developers`. Achieve the best performance by packing all your filters in a single `ForSetDevelopers` instead of sending multiple `ForSetDevelopers`-s. For example, use `repogroups` to request separate metrics for several repository sets. - `repositories` RepositoryID[], required: Set of repositories. An empty list raises a bad response 400. Duplicates are automatically ignored. - `developers` DeveloperID[], required: A set of developers. An empty list disables the filter and includes everybody. 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[] - `aggregate_devgroups` array[]: Lists of indexes in `repositories` or `developers` that define independent groups that must be processed individually. The groups may have intersections. - integer[] - `labels_include` string[]: PRs must be labeled with at least one name from this list so that the related metrics include them. - `labels_exclude` string[]: PRs must not be labeled with any name from this list so that the related metrics exclude them. - `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. - `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` array[], required: The sequence matches `CalculatedDeveloperMetricsItem.for.developers`. - CalculatedLinearMetricValues[]: 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` DeveloperMetricID[], required: Repeats `DeveloperMetricsRequest.metrics`. - `date_from` string, date, required: Repeats `DeveloperMetricsRequest.date_from`. - `date_to` string, date, required: Repeats `DeveloperMetricsRequest.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. ## 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-03-03** `f9fdd9fbfc25`: 2 info - added the new optional request property `for/items/jira/status_categories` - added the optional property `calculated/items/for/jira/status_categories` to the response with the `200` status - **2023-02-23** `ac90624ec263`: 1 breaking - the `granularities` request property's minItems was increased to `1` [Operation history](https://skmtc.dev/athenian/apis/title/changes/metrics/developers/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)