Important: This is a legacy version of the Coding metrics API. If you're a Flow cloud customer, please use the updated Coding metrics API when making API calls, and refer to the documentation for migration information. This legacy API will be sunsetted February 7, 2025. Reach out to your Flow contact if you have more questions. If you use Flow Enterprise Server, continue to use this legacy API.
The Coding metrics API provides the coding metrics from the Team health insights report for use outside of Flow.
Note: The Coding metrics API is not documented in Flow's interactive API documentation (opens in new tab).
The Coding metrics API returns 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.
In this article
Permissions
Users calling the Coding 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 Coding metrics API. If your user can’t call the Coding 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 Coding 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 |
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."],
"include_nested_teams":
["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 Coding 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 Coding 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
}
]
}