Collaboration metrics API

Tags: Flow

The collaboration metrics API provides the collaboration and PR metrics from the Team health insights report for use outside of Flow.


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:

  1. In the top navigation, click Settings.

  2. Under User management, click Users.

  3. Search for the user you want to give the Metrics API permission to.

  4. Click the user’s name.

  5. Click the Access tab.

  6. In the API access column, check the Metrics API box.

  7. Click Save changes.

  8. Repeat this process for all users whom you want to access the Collaboration metrics API.

back to top


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/.

back to top


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:

  1. Click Authorize.
  2. Put Bearer <Flow API key> in the value field. Click Authorize. You must include Bearer in the field.
  3. Click Try it out. Input parameters as desired.
  4. Click Execute.

back to top


Results

This API returns average values over a specific time period for the following collaboration metrics:

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.

back to top


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

back to top


If you need help, please contact Pluralsight Support.