If you use the legacy Coding metrics API to extract Coding metrics data, migrate to the updated Coding metrics API as soon as possible. This new API contains additional information in response as well as more consistency with other Flow metrics APIs.
When migrating, you will need to change the base URL you’re calling along with the request parameters. You may continue to use the same API key as you have in the past. The metric values received should be consistent with the legacy API.
Permissions
Users calling the Coding API must have the Metrics API permission as well as a valid and unique API key. To enable API permissions for users, you must have the Manage User Permissions permission. Learn more about administrative permissions and API keys in Flow.
Important: If a user does not have both the Metrics API permission and an API key, they can't use the Coding metrics API. If your user can't call the Coding metrics API, verify they have both the permission and a valid API key.
To enable the Metrics API permission for a user, make sure the permission is added to at least one role they are assigned to.
Calling the API
Call the API endpoint over standard HTTPS. Use any tool or programming language that can add the authorization: Bearer <API Key> header.
The base URL for the API is https://flow-api.pluralsight.com/collaboration/code/metrics/
Supported parameters
The only required parameter is a date range, formatted as [YYYY-MM-DD:YYYY-MM-DD]. The start of the date range must be first, and the end of the date range must be second. The date range must match the format exactly.
Learn more about additional parameters for this API in the Swagger documentation (opens in new tab).
Tip: You can also use the Swagger documentation to receive responses from the API. To do this:
- Click Authorize.
- Put
Bearer <Flow API key>in the value field. Click Authorize. You must includeBearerin the field. - Click Try it out. Input parameters as desired.
- Click Execute.
Available parameters
| Parameter | Description | Example |
|---|---|---|
| date_range | Specifies the date range to look for commits in. Commits authored during the selected date range are included. | date_range=[2024-01-01:2024-04-21] |
| apex_user_id | Matches on the ID of a specific apex user. A team ID must also be present when using this parameter. | apex_user_id=12345 |
| apex_user_id__in | Matches on a comma-separated list of apex user IDs | apex_user_id__in=12345,23456 |
| team_id | Matches on an ID of a specific Flow team | team_id=12345 |
| team_id__in | Matches on a comma-separated list of provided Flow team IDs | team_id__in=12345,23456 |
| repo_id | Matches on exact repo ID | repo_id=12345 |
| repo_id__in | Matches on a comma-separated list of repo IDs | repos_id__in=12345,23456 |
| repo_id_not__in | Matches on all repo IDs except those in the provided comma-separated list | repo_id_not__in=1234,23456 |
| repo_tag_id | Matches on an exact repo tag ID | repo_tag_id=5123 |
| repo_tag_id__in | Matches on a comma-separated list of repo tag IDs | repo_tag_id__in=5123,6234 |
| repo_name | Matches on any repo name which contains the provided value | repo_name=DevRepo |
| include_nested_teams | Determines whether data from nested teams is included. Defaults to false | include_nested_teams=true |
| include_weekly_data | Determines whether to include a week-by-week breakdown of the metric values in addition to the period aggregates. Defaults to false. | include_weekly_data=true |
Response format
This API returns average values over a specific time period for the following coding metrics:
-
active_days: Coding days -
commit_count: Commits per day -
total_impact: Impact -
total_efficiency: Efficiency
For each metric, the API returns the period average and the trend. Trends only display if your date range includes four or more Monday to Sunday weeks. Set the include_weekly_data parameter to true to add weekly values for each week in the selected period for all metrics included in the response. This parameter is set to false by default.
The response also includes percentile benchmark data including the 25th, 50th and 75th percentiles, as well as the minimum and maximum value for each metric from our benchmark data.
The results from this API match the corresponding results in Team health insights for these metrics.
Tip: To use the Coding metrics API, you may need to find the IDs for various Apex users, teams, or repos. Use the Users API, Teams API, and Repos API to find these values before using the Coding metrics API to get metric data for those selections. Make sure you have the permissions associated with each endpoint to receive data.