Updated Coding metrics API

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 returns additional information in its responses and is more consistent with other Flow metrics APIs.

When migrating, you will need to update the base URL you’re using and the request parameters. You can 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 and a valid, 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.

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, ensure the permission is added to at least one role to which they are assigned.

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://api.appfireflow.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 include Bearer in the field.
Click Try it out. Input parameters as desired.
Click Execute.

Available parameters

Parameter	Description	Example

Parameter	Description	Example
`date_range`	Specifies the date range to search for commits. 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 that 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 values for each metric from our benchmark data.

The results from this API match the corresponding results in Team health insights for these metrics.

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.