The Metrics API provides the coding metrics from the Team health insights report for use outside of Flow.
Note: The Metrics API is not documented in Flow's interactive API documentation (opens in new tab).
Who can use this?
| Core | Plus | ||
| ✓ |
The Metrics API averages Coding days, Commits per day, Impact, and Efficiency for the time period selected in the report’s date range filter.
If you haven’t used the Flow customer API before, learn more about how to make a Flow API call.
Permissions
Users calling the Metrics API must have 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 permission and the API key, they can't use the Metrics API. If your user can’t call the Metrics API, verify they have both the permission and API key.
To enable the Metrics API permission:
- In the Settings left pane navigation 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 you want to access the Metrics API.
Note: These changes don't affect existing permissions for other Flow customer APIs.
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 this API is: https://flow.pluralsight.com/v3/customer/metrics/code_fundamentals/period_metrics/.
Supported parameters
| Parameter | Required or Optional | Description | Example |
|---|---|---|---|
| start_date | Required | Specifies the start of the date range. | start_date=2021-05-01 |
| end_date | Optional | Specifies the end date of the date range. If unspecified, uses the current date. | end_date=2021-05-15 |
| include_nested_teams | Optional | Determines whether data from nested teams are included. | include_nested_teams=true include_nested_teams=false |
| aggregate | Optional | Matches users and teams visible at aggregate depth. Shows anonymized aggregate metrics without individually identifiable details. | aggregate=true aggregate=false |
| atomic | Optional | Matches users and teams visible at atomic depth. Shows granular or individually identifiable details in metrics if you have the rights to see them. | atomic=true atomic=false |
| resolution | Required | Specifies whether metrics are averaged over a week or date range.
| resolution=week resolution=period |
| apex_user_id | Optional | Matches on the ID of a specific apex user. | apex_user_id=12345 |
| apex_user_id__in | Optional | Matches on a set of provided apex user IDs. | apex_user_id__in=12,34,56 |
| team_id | Optional | Matches on an ID of a specific Flow team. | team_id=12345 |
| team_id__in | Optional | Matches on a set of provided Flow team IDs. | team_id__in=21,34,65,67 |
| repo_id | Optional | Matches on exact repo ID. | repo_id=12345 |
| repo_id__in | Optional | Matches on a set of provided repo IDs. | repo_id__in=1,2,3,4 |
| repo_id_not__in | Optional | Matches on a all repo IDs except the provided repo ID set. | repo_id_not__in=67,45,34 |
| repo_tag_id | Optional | Matches on an exact repo tag ID. | repo_tag_id=5123 |
| repo_tag_id__in | Optional | Matches on a set of provided repo tag IDs. | repo_tag_id__in=34,21,78,45 |
| repo_name | Optional | Matches on any repo name which contains the search parameter. | repo_name=ExampleTeam |
Result formats
The API returns results in JSON. The shape of the data depends on the resolution flag.
Example results for when the resolution flag is set to week:
{
"count": 5,
"results": [
{
"period_start_date": "2021-05-31",
"active_days": 2.2,
"commit_count": 4.2,
"total_impact": 94.1,
"total_efficiency": 78.1
},
{
"period_start_date": "2021-06-07",
"active_days": 2.8,
"commit_count": 5.5,
"total_impact": 111.1,
"total_efficiency": 58
},
{
"period_start_date": "2021-06-14",
"active_days": 2.9,
"commit_count": 3.7,
"total_impact": 114.4,
"total_efficiency": 65.1
},
{
"period_start_date": "2021-06-21",
"active_days": 2.7,
"commit_count": 3.9,
"total_impact": 122.9,
"total_efficiency": 76.9
},
{
"period_start_date": "2021-06-28",
"active_days": 1.6,
"commit_count": 5.7,
"total_impact": 85.1,
"total_efficiency": 65.4
}
]
}
Note: Weeks with no data are omitted from the results.
Example results for when the resolution flag is set to period:
{
"count": 1,
"results": [
{
"active_days": 2.8,
"commit_count": 4.5,
"total_impact": 121.7,
"total_efficiency": 68.2
}
]
}
Error format
If there is an error in any of the request parameters, the request will return an error.
Example error:
{
"start_date":
["Provide a valid date. Date cannot be more than 3 years prior to now."],
"aggregate":
["Provide a valid choice. 'yes' is not one of the available choices: ['true', 'false']"],
"resolution":
["Provide a valid choice. 'month' is not one of the available choices: ['period', 'week']"]
}
If there is an error in the request parameters, the system returns a non-200 status code in addition to the response above. This is normally a 400 error for any form of input error, and a 500 error for any back-end exceptions. For back-end exceptions, the error is generic.
Example generic error:
{
"error": ["Unknown error occurred"]
}
Examples
Get Coding 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 Coding metrics over a specified period, insert the team ID in the team_id parameter of the Metrics API endpoint. Set resolution to period.
Example query: https://flow.pluralsight.com/v3/customer/metrics/code_fundamentals/period_metrics/?start_date=2021-06-01&end_date=2021-06-30&team_id=12345&include_nested_teams=true&resolution=period.
Example response:
{
"count": 1,
"results": [
{
"active_days": 2.4,
"commit_count": 3.5,
"total_impact": 97.7,
"total_efficiency": 83.1
}
]
}
To get the weekly averages of your team's Coding metrics for a specified period, insert the team ID in the team_id parameter of the Metrics API endpoint. Set resolution to week.
Example query: https://flow.pluralsight.com/v3/customer/metrics/code_fundamentals/period_metrics/?start_date=2021-06-01&end_date=2021-06-30&team_id=12345&include_nested_teams=true&resolution=week.
Note: Weeks with no commit activity are omitted from the response.
Example response:
{
"count": 5,
"results": [
{
"period_start_date": "2021-05-31",
"active_days": 1.0,
"commit_count": 4.0,
"total_impact": 18.5,
"total_efficiency": 52.6
},
{
"period_start_date": "2021-06-07",
"active_days": 1.0,
"commit_count": 4.0,
"total_impact": 33.8,
"total_efficiency": 94.9
},
{
"period_start_date": "2021-06-14",
"active_days": 3.0,
"commit_count": 3.5,
"total_impact": 118.0,
"total_efficiency": 91.4
},
{
"period_start_date": "2021-06-21",
"active_days": 2.5,
"commit_count": 4.0,
"total_impact": 151.7,
"total_efficiency": 78.1
},
{
"period_start_date": "2021-06-28",
"active_days": 3.0,
"commit_count": 2.3,
"total_impact": 87.4,
"total_efficiency": 77.9
}
]
}
Get Coding metrics for an individual
To get Coding 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 coding 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 and set resolution to period to return the Coding metrics’ overall averages across a specified period.
Example query: https://flow.pluralsight.com/v3/customer/metrics/code_fundamentals/period_metrics/?start_date=2021-06-01&end_date=2021-06-30&apex_user_id=1234567&resolution=period.
Example response:
{
"count": 1,
"results": [
{
"active_days": 3.3,
"commit_count": 4.2,
"total_impact": 154.9,
"total_efficiency": 71.1
}
]
}
To get weekly averages, use the apex_user_id parameter and set resolution to week.
Example query: https://flow.pluralsight.com/v3/customer/metrics/code_fundamentals/period_metrics/?start_date=2021-06-01&end_date=2021-06-30&apex_user_id=1234567&resolution=week.
Example response:
{
"count": 5,
"results": [
{
"period_start_date": "2021-05-31",
"active_days": 2.8,
"commit_count": 3.9,
"total_impact": 123.8,
"total_efficiency": 76.2
},
{
"period_start_date": "2021-06-07",
"active_days": 3.0,
"commit_count": 5.1,
"total_impact": 136.6,
"total_efficiency": 60.3
},
{
"period_start_date": "2021-06-14",
"active_days": 3.2,
"commit_count": 3.9,
"total_impact": 141.2,
"total_efficiency": 67.1
},
{
"period_start_date": "2021-06-21",
"active_days": 3.2,
"commit_count": 3.6,
"total_impact": 168.4,
"total_efficiency": 79.3
},
{
"period_start_date": "2021-06-28",
"active_days": 2.1,
"commit_count": 4.4,
"total_impact": 99.3,
"total_efficiency": 74.1
}
]
}
If you need help, please contact Pluralsight Support.