The collaboration metrics API provides the collaboration and PR metrics from the Team health insights report for use outside of Flow.
Who can use this?
| Core | Plus | ||
| ✓ |
Permissions
Users calling the Collaboration metrics API must have the Metrics API permissions as well as a valid and unique API key. To enable API permissions for users, enable 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 the API key, they can't use the Collaboration metrics API. If your user can’t call the Collaboration metrics API, verify they have both the permission and API key.
To enable the Metrics API permission:
In the top navigation, click Settings.
Under User management, click Users.
Search for the user you want to give the Metrics API permission to.
Click the user’s name.
Click the Access tab.
In the API access column, check the Metrics API box.
Click Save changes.
Repeat this process for all users whom you want to access the Collaboration metrics API.
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/pullrequest/metrics/.
Supported parameters
The only required parameter is a date range, formatted like [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.
If you use one of the apex_user_id parameters, you must also include a team_id parameter to select which PRs to view the user’s metrics in context with.
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.
Results
This API returns average values over a specific time period for the following collaboration metrics:
- Rework time
Note: Rework time is the same as PR iteration time.
- Iterated PRs
PR count
This is the total number of PRs merged in the selected time period.
For each metric, the API returns the period average, the trend, and the target, if you have one set. Trends only display if your date range includes four or more Monday to Sunday weeks.
The results from this API match the corresponding results in Review collaboration for these metrics.
Tip: To use the Collaboration 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 Collaboration metrics API to get metric data for those selections. Make sure you have the permissions associated with each endpoint to receive data.
Example responses
Get specific Collaboration metrics
By default, the API returns all Collaboration metrics and all fields for those metrics. To show only certain metrics and fields, append the metrics and fields parameters to your query.
Example query: https://flow-api.pluralsight.com/collaboration/pullrequest/metrics/?date_range=[2023-01-01:2023-04-01]&metrics=reaction_time,time_to_merge&fields=average,trend
Example response:
{
"reaction_time" {
"average": 13.22,
"trend": -33.88
},
"time_to_merge": {
"average": 40.87,
"trend": 2.46
}
}
Get Collaboration metrics for a team
First, use the Teams API endpoint to find your team ID. In the response, note the team id for use in the next step.
Example query: https://flow.pluralsight.com/v3/customer/core/teams/?name=ExampleTeam.
Example response:
{
"count":1,
"next":null,
"previous":null,
"results":[
{
"id":12345,
"name":"ExampleTeam",
"description":"",
"org":1234,
"avatar":null,
"vendor":null,
"created_at":"2020-09-22T15:55:26.482759",
"parent":54321,
"path":"11188.99591.52870",
"ancestors":["ParentTeam","AnotherTeam","ExampleTeam"],
"visibility":"SHOW",
"team_level":3,
"inherited_depth":"atomic",
"nested_teams":0,
"all_users":4,
"unnested_users":4,
"depth":"inherit"
}
]
}
To get the overall average of your team’s Collaboration metrics over a specified period, insert the team ID in the team_id parameter of the Collaboration metrics API endpoint.
Example query: https://flow-api.pluralsight.com/collaboration/pullrequest/metrics/?date_range=[2023-01-01:2023-04-01]&team_id=12345
Note: This query only considers PRs authored by direct members of the team. If you want to include PRs authored by members of a nested team, add include_nested_teams=true to the query.
Example response:
{
"reaction_time": {
"average": 13.22,
"trend": -33.88
},
"responsiveness": {
"average": 5.87,
"trend": 65.91
},
"time_to_merge": {
"average": 40.87,
"trend": 2.46
},
"time_to_first_comment": {
"average": 18.17,
"trend": 15.87
},
"rework_time": {
"average": 12.86,
"trend": 101.56
},
"iterated_prs": {
"average": 37.03,
"trend": -5.64
},
"unreviewed_prs": {
"average": 1.91,
"trend": 393.16
},
"thoroughly_reviewed_prs": {
"average": 39.52,
"trend": 6.73
},
"pr_count": 1045
}
Get Collaboration metrics for an individual
To get Collaboration metrics for a single user, find the user’s Apex user ID in the user’s endpoint of the Flow customer API. See Users API to learn more about retrieving a user’s Apex user ID. Note the ID for the user you want to see the Collaboration metrics for.
Example query: https://flow.pluralsight.com/v3/customer/core/users/?team_member=12345.
Note: This example uses the team ID from the previous example to find the Apex user ID. Your request may look different if you use a different parameter to find the user's Apex user ID.
Example response:
{
"count": 4,
"next": null,
"previous": null,
"results": [
{
"id": 1234567,
"name": "Stephanie Ventura",
"email": "stephanie-ventura@examplecompany.com",
"hidden_from_reports": false,
"org_id": 1234,
"created_at": "2019-06-24T21:50:40.880538",
"teams": [
{
"id": 12345,
"name": "ExampleTeam",
"description": "",
"org": 1234,
"avatar": null,
"vendor": null,
"created_at": "2020-09-22T15:55:26.482759",
"parent": 54321,
"path": "11188.99591.52870",
"visibility": "SHOW",
"inherited_depth": null,
"nested_teams": 0,
"all_users": 4,
"unnested_users": 4,
"depth": "inherit"
},
{
...
}
],
"has_login": true,
"pending_invitation": false,
"alias_count": 8,
"last_activity_at": "2021-08-09T12:24:18",
"first_activity_at": "2019-06-24T19:13:02.504000",
"avatar_url": "https://secure.gravatar.com/avatar/example.jpg?s=96&d=retro&r=g",
"avatar_exists": false,
"invitation_id": null,
"login_enabled": true,
"is_saml": true,
"is_group_member": false,
"hidden": false,
"hidden_by": null,
"hidden_at": "2020-11-17T04:07:57.948366",
"login": {
...
}
},
{
...
},
{
...
},
{
...
}
]
}
Once you have the Apex user ID, insert it into the apex_user_id parameter to return the Collaboration metrics’ overall averages across a specified period. Also include the team_id for the team you want to consider the user’s Collaboration metrics in context with.
Example query: https://flow-api.pluralsight.com/collaboration/pullrequest/metrics/?date_range=[2023-01-01:2023-04-01]&team_id=12345&apex_user_id=1234567
Example response:
{
"reaction_time": {
"average": 0.03
},
"responsiveness": {},
"time_to_merge": {
"average": 32.4,
"target": 24.0
},
"time_to_first_comment": {
"average": 0.09,
"target": 2.0
},
"rework_time": {
"average": 32.08,
"target": 18.0
},
"iterated_prs": {
"average": 66.67,
"target": 0.2
},
"unreviewed_prs": {
"average": 0.0,
"target": 0.2
},
"thoroughly_reviewed_prs": {
"average": 66.67,
"target": 0.65
},
"pr_count": 3
If you need help, please contact Pluralsight Support.