Legacy Coding metrics API

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 in 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 is not documented in Flow's interactive API documentation.

The Coding metrics API provides the coding metrics from the Team health insights report for use outside of Flow.

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

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.

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.

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://<workspace>.appfireflow.com/v3/customer/metrics/code_fundamentals/period_metrics/

Supported parameters

Parameter	Required or Optional	Description	Example

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. `period` returns averages for each metric over the given date range. `week` returns details for each week over the given 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
        }
    ]
}

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 the request parameters contain an error, 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://<workspace>.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 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://<workspace>.appfireflow.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://<workspace>.appfireflow.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

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

{
    "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://<workspace>.appfireflow.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://<workspace>.appfireflow.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
        }
    ]
}