--- title: "Collaboration metrics API" canonical: "https://support.appfire.com/space/FD/1802076189/Collaboration%20metrics%20API" format: markdown --- > Macro (aura-html) The collaboration metrics API provides 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 and a valid, unique API key. To enable API permissions for users, enable the Manage User Permissions permission. Learn more about [administrative permissions](https://appfire.atlassian.net/wiki/spaces/FD/pages/1802142015) and [API keys](https://appfire.atlassian.net/wiki/spaces/FD/pages/1802010677) in Flow. > ⚠️ 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 you want to grant access to 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 ` header. The base URL for the API is `https://api.appfireflow.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)](https://api.appfireflow.com/collaboration/docs). > ✅ **Tip**: You can also use the Swagger documentation to receive responses from the API. To do this: > ✅ > ✅ 1. Click **Authorize**. > ✅ 2. Put `Bearer ` 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**. ## Results This API returns average values over a specific time period for the following Collaboration metrics: - [Time to merge](https://appfire.atlassian.net/wiki/spaces/FD/pages/1802010845) - [Time to first comment](https://appfire.atlassian.net/wiki/spaces/FD/pages/1801945431) - [Rework time](https://appfire.atlassian.net/wiki/spaces/FD/pages/1802273018) (Rework time is the same as PR iteration time) - [Iterated PRs](https://appfire.atlassian.net/wiki/spaces/FD/pages/1802666177) - [Unreviewed PRs](https://appfire.atlassian.net/wiki/spaces/FD/pages/1801912594) - [Thoroughly reviewed PRs](https://appfire.atlassian.net/wiki/spaces/FD/pages/1802338547) - [Reaction time](https://appfire.atlassian.net/wiki/spaces/FD/pages/1801912570) - [Responsiveness](https://appfire.atlassian.net/wiki/spaces/FD/pages/1801977972) - PR count - This is the total number of PRs merged in the selected time period that were created by a member of the selected team and/or the selected user. For each metric, the API returns the period average, the trend, and the target, if one is set. Trends are displayed only 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 results from this API match the corresponding results in [Review collaboration](https://appfire.atlassian.net/wiki/spaces/FD/pages/1802568056) for these metrics. > ✅ To use the Collaboration metrics API, you may need to find the IDs for various Apex users, teams, or repos. Use the [Users API](https://help.pluralsight.com/hc/en-us/articles/24285931632916), [Teams API](https://help.pluralsight.com/hc/en-us/articles/24286001376404), and [Repos API](https://help.pluralsight.com/hc/en-us/articles/24286004080276) to find these values before using the Collaboration metrics API to get metric data for those selections. Make sure you have the required permissions for each endpoint to receive data. ## Examples By default, the API returns all Collaboration metrics and their fields. ### Get specific Collaboration metrics To show only certain metrics and fields, append the metrics and fields parameters to your query. - Example query: `https://api.appfireflow.com/collaboration/pullrequest/metrics/?date_range=[2023-01-01:2023-04-01]&metrics=reaction_time,time_to_merge&fields=average,trend` Example response: ```json { "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](https://appfire.atlassian.net/wiki/spaces/FD/pages/1802011038) endpoint to find your team ID. In the response, note the team `id` for use in the next step. - Example query: `https://api.appfireflow.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://api.appfireflow.com/collaboration/pullrequest/metrics/?date_range=[2023-01-01:2023-04-01]&team_id=12345` > ℹ️ This query considers only PRs authored by direct team members. If you want to include PRs authored by members of a nested team, add `include_nested_teams=true` to the query. Example response: ```json { "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](https://appfire.atlassian.net/wiki/spaces/FD/pages/1802404091) 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://api.appfireflow.com/v3/customer/core/users/?team_member=12345`. > ℹ️ 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: ```json {     "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://api.appfireflow.com/collaboration/pullrequest/metrics/?date_range=[2023-01-01:2023-04-01]&team_id=12345&apex_user_id=1234567` Example response: ```json { "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 ``` ### Get Collaboration metrics for a user attribute > 📝 When using the user attribute filter, ensure the attribute name exactly matches the database entry and that you replace any spaces between attribute names with an underscore (`_`). > 📝 > 📝 Attribute names and their value names can be found in **Settings** > **User Management** > **[User attributes](https://appfire.atlassian.net/wiki/spaces/FD/pages/3044311307)** (the **Manage Users & Teams** permission is required). To show Collaboration metrics for a specific [user attribute](https://appfire.atlassian.net/wiki/spaces/FD/pages/3045031988), add `?user_metadata__text__=` to your query. - Example query for **Programming Language** (attribute name) and **Python** (attribute value): `GET /collaboration/pullrequest/metrics/?user_metadata__text__Programming_Language=python` - Example query for **Hire Date** (attribute name) and **01/15/2024** (attribute value): `GET /collaboration/pullrequest/metrics/?user_metadata__date__Hire_Date=2024-01-15`