Measurements V2

LinearB customers on Business or Enterprise plans have the option to export Metrics data that has already been processed by the platform and leverage this information to:

Create custom reports
Export to other data visualization tools

Limitations

LinearB measurements API is currently limited to Git metrics
PM metrics like Velocity/Investment Profile/Time Distribution are not supported at this point.

Usage

The Measurements API is designed to operate in two ways.

Integration - The request generate a report and provides the report in JSON format in the response
Export - The request generates a report and drops it as a CSV or JSON file in Amazon S3 bucket. A link for the file is returned in the response

Info

If the request filter provided end up with no data, then also the system will not generate a report and provide a response with the code 204 (No Content).

Create measurements report (JSON)

This API endpoint should be used to instantly obtain metrics data from LinearB. It offers the capability to retrieve all available metrics. It provides the ability to retrieve all available metrics, and for those that support it, you can opt for aggregation methods such as p75, p50, and average calculations.

HTTP request

POST  https://public-api.linearb.io/api/v2/measurements

Body parameter

Property name	Value	Description
requested_metrics (required)	Array of objects	The list of metrics to export Valid values are: supported metrics
group_by	string	Field to group by Valid values are: "organization", "team", "contributor","repository" ,"label" Restrictions: Grouping is restricted to a maximum of 10 repositories and 3 Pull Request labels.
order_by	string	Field to order by
contributor_ids	Array of integers	The list of contributors to filter by
repository_ids	Array of integers	The list of repositories to filter by
team_ids	Array of integers	The list of teams to filter by
service_ids	Array of integers	The list of services to filter by
labels	Array of strings	The list of PR labels to filter by Restrictions: Filtering by labels is restricted to 3 PR labels If the grouping is based on labels, the results will be grouped according to the specified labels. For other group by values, the results will be filtered based on the provided labels
time_ranges	Array of objects	Specifying the time ranges for pulling measurements to run the report requires detailing each time range, whether it's a single range or multiple ranges. Ensure inclusion of both "before" and "after" parameters. For instance, {"after": "2022-05-27", "before": "2022-05-29"}.
roll_up	string	Set the intervals to break down the data. Example: 2d (two days), 1w (one week), 1m (one month), or 'custom' to utilize the specified time ranges as intervals.
limit	integer	Max amount of objects in the response. When request for multiple contributors, teams or repositories, limit should be more or equal of amount of passed ids (or data will be returned partially)
offset	integer	Used for pagination, defines the offset for the query
return_no_data	boolean	If true, then will return nullable values, otherwise,will drop them.

Supported metrics

Name	Aggregation	Description	Units
branch.computed.cycle_time	p75, p50, avg	Full cycle time (Coding time + Pickup time + Review time + Time to production)	min.
branch.time_to_pr	p75, p50, avg	Coding time (Time to PR)	min.
branch.time_to_review	p75, p50, avg	Pickup time (Time to review)	min.
branch.review_time	p75, p50, avg	Review time	min.
branch.time_to_prod	p75, p50, avg	Time to production (Time to deploy)	min.
pr.merged.size	p75, p50, avg	The sum of PR sizes of merged PRs	lines of code
pr.merged		The number of PRs that got merged	count
pr.review_depth		The sum of comments divided by the sum of PRs	lines of comments
commit.activity.new_work.count		The total new lines of code	count
commit.total_changes		The total lines of code that have been replaced	lines of code
commit.activity.refactor.count		The total lines of code that have been replaced that are older then 25 days	lines of code
commit.activity.rework.count		The total lines of code that have replaced code written within the last 25 days, but outside this branch	lines of code
pr.merged.without.review.count		The number of PRs that got merged without review	count
commit.total.count		The sum of commits	count
pr.new		The number of opened PRs	count
pr.reviews		The number of reviews on all PRs	count
releases.count		The number of releases	count
commit.activity_days		The amount of day of developer activity (commit/comment/PR/merge/review)	days
branch.state.computed.done		Number of branches that reached state done	count
branch.state.active		Number of active branches	count
pm.mttr		Mean time to repair	mim.
pm.cfr.issues.done		The sum of issues that are considered as incidents that reached a done state	count

Examples

Create measurements report with time ranges

{
  "group_by": "organization",
  "roll_up": "custom",
  "requested_metrics": [
    {
      "name": "branch.computed.cycle_time",
      "agg": "p75"
    },
    {
      "name": "releases.count"
    }
  ],
  "time_ranges": [
    {
      "after": "2022-05-27",
      "before": "2022-05-29"
    },
    {
      "after": "2022-05-30",
      "before": "2022-06-05"
    },
    {
      "after": "2022-06-06",
      "before": "2022-06-12"
    },
    {
      "after": "2022-06-13",
      "before": "2022-06-19"
    }
  ]
}

Create measurements report before and after

{
  "group_by": "organization",
  "roll_up": "1w",
  "requested_metrics": [
    {
      "name": "branch.computed.cycle_time",
      "agg": "p75"
    },
    {
      "name": "branch.computed.cycle_time",
      "agg": "avg"
    }
  ],
  "time_ranges": [
    {
      "after": "2022-05-27",
      "before": "2022-06-29"
    }
  ]
}

Create measurements report for specific repositories

{
  "group_by": "organization",
  "roll_up": "1d",
  "repository_ids": [
    456801317,
    1235235
  ],
  "requested_metrics": [
    {
      "name": "branch.time_to_prod",
      "agg": "p50"
    }
  ],
  "time_ranges": [
    {
      "after": "2022-05-27",
      "before": "2022-06-29"
    }
  ]
}

Create measurements report for specific teams

{
  "group_by": "team",
  "roll_up": "1mo",
  "team_ids": [
    5273,
    58
  ],
  "requested_metrics": [
    {
      "name": "branch.time_to_prod",
      "agg": "p50"
    },
    {
      "name": "branch.time_to_pr",
      "agg": "avg"
    }
  ],
  "time_ranges": [
    {
      "after": "2022-05-27",
      "before": "2023-06-29"
    }
  ]
}

Responses

200 - Successful Response

[
    {
    "after": "2022-05-27",
    "before": "2022-05-29",
    "metrics": [
      {
        "organization_id": 1697464851,
        "branch.computed.cycle_time:p75": 2872,
        "releases.count": 8
      }
    ]
      },
      {
        "after": "2022-05-30",
        "before": "2022-06-05",
        "metrics": [
          {
            "organization_id": 1697464851,
            "branch.computed.cycle_time:p75": 8048,
            "releases.count": 35
          }
        ]
      },
      {
        "after": "2022-06-06",
        "before": "2022-06-12",
        "metrics": [
          {
            "organization_id": 1697464851,
            "branch.computed.cycle_time:p75": 45333,
            "releases.count": 39
          }
        ]
      },
      {
        "after": "2022-06-13",
        "before": "2022-06-19",
        "metrics": [
          {
            "organization_id": 1697464851,
            "branch.computed.cycle_time:p75": 2857,
            "releases.count": 34
          }
        ]
      }
]

400 - Bad Request

401 - Unauthorized

405 - Method Not Allowed

422 - Validation Error

500 - Internal Server Error

Export measurements report

This API endpoint enables the export of metrics V2 data in CSV or JSON format. Will return S3 URL in the response. Each file uploaded to S3 will be stored with expiration period policy, so it will be deleted after will reach the threshold.

HTTP request

POST  https://public-api.linearb.io/api/v2/measurements/export

Query parameter

Parameter name	Value	Description
file_format	string	Defines the format of the output file Valid values are: "json" and "csv" (Default: "json")

Body parameter

Property name	Value	Description
requested_metrics (required)	Array of objects	The list of metrics to export Valid values are: supported metrics
group_by	string	Field to group by Valid values are: "contributor", "repository", "team", "organization"
order_by	string	Field to order by
contributor_ids	Array of integers	The list of contributors This parameter must be passed if grouping by "contributor"
repository_ids	Array of integers	The list of repositories This parameter must be passed if grouping by "repository"
team_ids	Array of integers	The list of teams This parameter must be passed if grouping by "team"
service_ids	Array of integers	The list of services This parameter must be passed if grouping by "service"
time_ranges	Array of objects	Should not be passed if before and after are defined. Each time range should contain before and after. after & before values: string (timestamp ISO 8601 format) Example: [{"after": "2022-05-27", "before": "2022-05-29"},...]
limit	integer	Max amount of objects in the response. When request for multiple contributors, teams or repositories, limit should be more or equal of amount of passed ids (or data will be returned partially)
offset	integer	Used for pagination, defines the offset for the query
return_no_data	boolean	If true, then will return nullable values, otherwise,will drop them.

Responses

200 - Successful Response

{
  "report_url": "string",
  "detail": "string"
}

202 - Request to create report is accepted, but not ready yet

204 - No Content. Does not exist or has expired

400 - Bad Request

401 - Unauthorized

405 - Method Not Allowed

422 - Validation Error

500 - Internal Server Error

504 - Gateway Timeout