Skip to main content
Deutsch (Deutschland) Español Français Hebrew (Israel) Italiano Português

Measurements V2 API

Heather Hazell
Updated

Use the Measurements V2 API to export metrics that LinearB has already computed from your Git data. You can use these reports to build custom dashboards, power external analytics, or feed data into your own BI tools.

TL;DR

  • Endpoint (JSON report): POST https://public-api.linearb.io/api/v2/measurements
  • Endpoint (export to file): POST https://public-api.linearb.io/api/v2/measurements/export
  • Reports support grouping and filtering by organization, team, contributor, repository, and services.
  • Only Git-based metrics are supported; project management (PM) metrics like Velocity and Investment Profile are not included.
  • If the filters return no data, the API responds with 204 No Content and no report is generated.

Overview

Measurements V2 lets you retrieve Git-derived metrics that LinearB has already processed, so you can:

  • Create custom reports and dashboards.
  • Export metrics to CSV or JSON for use in external tools.
  • Slice metrics by organization, team, contributor, repository, and labels.

Limitations:

  • Measurements V2 is currently limited to Git metrics.
  • PM metrics such as Velocity, Investment Profile, and Time Distribution are not supported.

The API works in two modes:

  1. Integration (JSON): Generate a report and receive the data directly in the JSON response.
  2. Export (file): Generate a report and export it as a JSON or CSV file to S3. The API returns a URL for download.

Important: If your filters result in no data, LinearB returns 204 No Content and does not generate a report.

Before You Begin

Authentication

All API requests require an API token.

  1. Go to Company Settings → API Tokens.
  2. Create (or reuse) an API token.
  3. Include it in every request header:
Authorization: Bearer <your_api_token>

Supported data

Measurements V2 provides access to Git-based delivery and quality metrics, such as cycle time, time-to-production, PR volume, code changes, releases, and select incident-related values.

See the Supported metrics section below for exact metric names and aggregation options.

1. Create measurements report (JSON)

Use this endpoint when you want to retrieve measurements directly in the response as JSON. This is typically used for integrations and programmatic analysis.

HTTP request

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

Body parameters

Required

  • requested_metrics (array of objects) – the list of metrics to include in the report.
    • Each object includes at least name, and optionally an aggregation (agg).
    • Valid metric names are listed in Supported metrics.

Optional

  • group_by (string) – field to group results by.
    • Valid values: "organization", "team", "contributor", "repository", "label".
    • Label grouping is limited to a maximum of 10 repositories and 3 PR labels.
  • order_by (string) – field to sort by.
  • contributor_ids (array of integers) – filter by specific contributors.
  • repository_ids (array of integers) – filter by specific repositories.
  • team_ids (array of integers) – filter by specific teams.
  • service_ids (array of integers) – filter by specific services.
  • labels (array of strings) – filter or group by PR labels.
    • Restricted to 3 labels.
    • If group_by = "label", results are grouped by the specified labels. Otherwise, labels act as filters.
  • time_ranges (array of objects) – one or more time windows for the report.
    • Each object must include after and before as date strings (e.g. "2022-05-27").
    • Use multiple ranges to produce a series of periods in one call.
  • roll_up (string) – how to break down data over time.
    • Examples: "2d" (two days), "1w" (one week), "1m" (one month), or "custom".
    • "custom" uses your time_ranges as the intervals.
  • limit (integer) – maximum number of records to return.
    • When requesting multiple contributors, teams, or repositories, limit should be at least the number of IDs; otherwise, results may be partial.
  • offset (integer) – offset for pagination.
  • return_no_data (boolean) – if true, returns nullable values instead of dropping entries with no data.

Supported metrics

The following metrics can be requested in requested_metrics. For some metrics, you may specify an aggregation (agg) such as "p75", "p50", or "avg".

Name Aggregation Description Units
branch.computed.cycle_time p75, p50, avg Full cycle time (coding + pickup + review + time to production). minutes
branch.time_to_pr p75, p50, avg Time from first commit to PR creation (coding time). minutes
branch.time_to_review p75, p50, avg Time from PR creation to review start (pickup time). minutes
branch.review_time p75, p50, avg Time spent in active review. minutes
branch.time_to_prod p75, p50, avg Time from PR merge to deployment (time to production). minutes
pr.merged.size p75, p50, avg Total size of merged PRs. lines of code
pr.merged — Number of PRs that were merged. count
pr.review_depth — Average review comments per PR. lines of comments
commit.activity.new_work.count — Total new lines of code. count
commit.total_changes — Total lines of code changed. lines of code
commit.activity.refactor.count — Lines of code replaced that are older than a threshold (refactor work). lines of code
commit.activity.rework.count — Lines of code replacing recent code (rework). lines of code
pr.merged.without.review.count — Number of PRs merged without review. count
commit.total.count — Total commit count. count
pr.new — Number of opened PRs. count
pr.reviews — Number of PR reviews. count
releases.count — Number of releases. count
commit.activity_days — Number of days with developer activity (commits, comments, PRs, reviews). days
branch.state.computed.done — Number of branches that reached done state. count
branch.state.active — Number of active branches. count
pm.mttr — Mean time to repair. minutes
pm.cfr.issues.done — Number of issues considered incidents that reached a done state. count

Examples

Create measurements report with custom 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 with a single time window
{
  "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

Returns an array of time windows, each with its own metrics object.

[
  {
    "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
      }
    ]
  }
]

Each metric key combines the metric name and aggregation (for example, branch.computed.cycle_time:p75).

Other status codes
  • 204 No Content – No data for the specified filters; no report is generated.
  • 400 Bad Request – Invalid payload or missing required fields.
  • 401 Unauthorized – Authentication failed or token missing.
  • 405 Method Not Allowed – HTTP method not supported for this endpoint.
  • 422 Validation Error – Field-level validation issues.
  • 500 Internal Server Error – Unexpected server-side error.

2. Export measurements report (file)

Use this endpoint to export metrics as a CSV or JSON file. The API returns an S3 URL where you can download the generated report. Files are stored with an expiration policy and may be removed after a certain period.

HTTP request

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

Query parameter

  • file_format (string, optional)
    • Defines the format of the exported file.
    • Valid values: "json", "csv".
    • Default: "json".

Body parameters

The request body has the same structure as the JSON report endpoint, with the following notes:

  • requested_metrics (required, array of objects) – list of metrics to export.
  • group_by (string) – field to group by.
    • Valid values: "contributor", "repository", "team", "organization".
  • order_by (string) – field to sort by.
  • contributor_ids (array of integers) – required if group_by = "contributor".
  • repository_ids (array of integers) – required if group_by = "repository".
  • team_ids (array of integers) – required if group_by = "team".
  • service_ids (array of integers) – required if group_by = "service".
  • time_ranges (array of objects) – should not be used if you separately define before and after; each range must include both.
  • limit (integer) – maximum number of results; keep at least as large as the number of IDs you request.
  • offset (integer) – pagination offset.
  • return_no_data (boolean) – if true, returns rows with null values instead of dropping them.

Responses

200 — Successful response
{
  "report_url": "string",
  "detail": "string"
}

report_url is the S3 URL where the exported file can be downloaded. The file may expire based on S3 lifecycle policies.

Other status codes
  • 202 Accepted – Report generation request accepted but not ready yet.
  • 204 No Content – No content; the report does not exist or has expired.
  • 400 Bad Request – Invalid request body or query parameters.
  • 401 Unauthorized – Missing or invalid API token.
  • 405 Method Not Allowed – HTTP method not supported.
  • 422 Validation Error – Validation issues in the request payload.
  • 500 Internal Server Error – Server-side error while creating the report.
  • 504 Gateway Timeout – Timeout while generating the report.

Verification & Troubleshooting

Verify a new measurements report
  1. Send a test request to POST /api/v2/measurements with a simple configuration (for example, one metric and a short time range).
  2. Confirm you receive a 200 response with at least one time window and metrics object.
  3. If you receive 204 No Content, relax filters (for example, wider date range or fewer IDs) and try again.
  4. Optionally, repeat the same body with POST /api/v2/measurements/export and verify that a report_url is returned.
Quick fixes (most common issues)
  • 204 No Content
    – The filters returned no data for the selected time ranges.
    – Try expanding the date range or removing some filters (IDs or labels).
  • Partial or truncated results
    – limit may be too low when requesting multiple contributors, teams, or repositories.
    – Increase limit so it is at least as large as the number of IDs you pass.
  • 401 Unauthorized
    – Verify your API token is active and belongs to the correct organization.
    – Confirm the Authorization: Bearer <your_api_token> header is present on every request.
  • 422 Validation Error
    – Check that required fields like requested_metrics and time_ranges are provided.
    – Ensure each time range includes both after and before in valid date format.
    – Confirm each metric name is one of the supported metrics.
Advanced troubleshooting (problem → cause → fix)
Problem Cause Fix
Report returns no metrics Time ranges or filters do not match any data (for example, before your organization started sending activity).
Or the requested metrics are not applicable for the selected scope.		 Test with a broader time_ranges window and fewer filters.
Start with a small set of well-known metrics like releases.count and branch.computed.cycle_time.
Unexpected grouping behavior group_by set to a field that does not match provided IDs (for example, grouping by team but filtering only by repository_ids).
Or label grouping used with more than the allowed number of repositories or labels.		 Align group_by with the IDs you pass (team_ids, repository_ids, etc.).
Respect the limit of 10 repositories and 3 labels when grouping by labels.
Export URL no longer works Exported report has expired based on S3 lifecycle policy, or the URL has been used after its retention period. Re-run POST /api/v2/measurements/export with the same filters to generate a new report and URL.
Gateway timeout (504) on export Very large report or heavy filters cause the export request to exceed processing time. Narrow the date range, reduce the number of IDs, or split the request into multiple, smaller queries.
If possible, start with the JSON report endpoint to validate filter behavior before exporting.

FAQ

Does Measurements V2 include PM metrics?

No. Measurements V2 is limited to Git-derived metrics. PM metrics such as Velocity and Investment Profile are not available via this API.

What time format should I use?

Use ISO 8601 date strings (for example, 2022-05-27) for after and before values in time_ranges.

Can I get both JSON and file export?

Yes. You can call /api/v2/measurements for JSON and /api/v2/measurements/export with the same body to generate a downloadable file.

What happens if I request too many IDs?

If limit is smaller than the number of contributors, teams, or repositories you request, the response may be partial. Always set limit to at least the number of IDs you pass.

 

For additional information, please visit our external API documentation

For additional technical support, please contact LinearB support.

Related articles