Skip to main content
Table of Contents

API - External Metrics

The External Custom Metrics API lets you report critical metrics from third-party tools (such as code coverage, security scanners, or CI systems) directly into LinearB. These metrics can be attached…

heather.hazell
Updated by heather.hazell

The External Custom Metrics API lets you report critical metrics from third-party tools (such as code coverage, security scanners, or CI systems) directly into LinearB. These metrics can be attached to pull requests, repositories, commits, or contributors, so you can analyze them alongside your delivery and quality signals.

TL;DR

  • Use POST /api/v1/report/metric to send metrics from external tools into LinearB.
  • Attach metrics to specific entities (PR, repo, commit, contributor) using the entity object.
  • Use tags to add context (for example, environment, tool name, or severity).
  • Metrics can then be surfaced in LinearB views and reports configured to use them.

Overview

Use this API when you want to send per-entity metrics such as:

  • Code coverage for a specific pull request or repository
  • Security vulnerabilities detected by a scanner
  • Build stability or test pass rate from CI

Each metric is reported with a name, timestamp, and optional numeric value, plus an optional entity (PR URL, repo URL, commit SHA, or contributor email) and tags for flexible filtering.

Before You Begin

Authentication

All requests must be authenticated with an API token.

  1. In LinearB, go to Company Settings → API Tokens.
  2. Create (or reuse) an API token.
  3. Include it on every request:
Authorization: Bearer <your_api_token>
Endpoint & method

All external custom metrics are reported to a single endpoint:

POST https://public-api.linearb.io/api/v1/report/metric
Required & optional fields

Required

  • metric_name — string (1–255 characters).
  • timestamp — string (ISO 8601 format).

Optional

  • value — number (metric value).
  • source — string (for example, the tool that produced the metric).
  • entity — object describing what this metric relates to. Can include one or more of:
    • pr_url
    • repo_url
    • commit_sha
    • contributor_email
  • tags — object (key/value pairs) for extra context and filtering.
When to use this vs Measurements v2
  • Use External Custom Metrics when you want to attach a metric to a specific PR, repo, commit, or contributor.
  • Use Measurements v2 when you want more general metrics over time (team/service/org level) without per-entity linkage.

Sending external custom metrics

1. Basic example (with all main fields)

Attach a metric to a pull request

This example sends a metric from a third-party tool and attaches it to a PR:

Endpoint

POST https://public-api.linearb.io/api/v1/report/metric

Example body

{
            "source": "gitstream",

            "timestamp": "2022-03-13T08:07:12.613Z",

            "metric_name": "ran_cm",

            "value": 2.5,

            "entity": {

              "pr_url": "https://github.com/hello/world/pull/1731"

            },

            "tags": {

              "my_tag": "my_value"

            }

          }

2. Metric with PR URL and commit SHA

Link a metric to both a PR and a commit

Endpoint

POST https://public-api.linearb.io/api/v1/report/metric

Example body

{
            "timestamp": "2022-03-13T08:07:12.613Z",

            "metric_name": "ran_cm",

            "entity": {

              "pr_url": "https://github.com/testorg/testrepo/pull/1234",

              "commit_sha": "my_commit_sha"

            }

          }

3. Metric scoped to a repository

Attach a metric to a repository

Example body

{
            "metric_name": "build_success_rate",

            "timestamp": "2024-10-02T12:30:00Z",

            "value": 0.98,

            "source": "jenkins",

            "entity": {

              "repo_url": "https://github.com/acme/api"

            }

          }

4. Metric scoped to a contributor

Attach a metric to a contributor email

Example body

{
            "metric_name": "coverage_delta",

            "timestamp": "2024-10-02T09:00:00Z",

            "value": 4.1,

            "source": "coverage-tool",

            "entity": {

              "contributor_email": "dev@acme.com"

            }

          }

Response codes

Successful response

On success, the API returns HTTP 200 and a JSON body containing a message and a metric identifier.

{
            "message": "string",

            "metric_uuid": "string"

          }
Error responses
  • 400 – Bad Request (invalid JSON or missing required fields).
  • 401 – Unauthorized (missing or invalid token).
  • 403 – Forbidden.
  • 405 – Method Not Allowed.
  • 422 – Validation Error.
  • 500 – Internal Server Error.
  • 504 – Gateway Timeout.

Verify & Troubleshooting

Verify a new external metric
  1. Send a test metric via POST /api/v1/report/metric using one of the example bodies above.
  2. Confirm you receive a 200 response and that the response body includes a metric_uuid (or success message).
  3. In LinearB, open the view or report configured to use this metric name and confirm the expected value appears after data processing completes.
Quick fixes (most common issues)
  • Metric appears to be ignored
    – Confirm metric_name and timestamp are present and correctly formatted.
    – Check that the entity fields (pr_url, repo_url, etc.) match data known to LinearB (for example, connected repos).
    – Verify that any dashboard or report is configured to use this metric_name.
  • 422 validation errors
    – timestamp must be ISO 8601 formatted (for example, 2024-01-03T10:15:30Z).
    – value, if provided, must be a valid JSON number.
    – metric_name must follow the allowed naming pattern (non-empty string within length limits).
  • 401 / 403 authentication issues
    – Confirm your token is valid and belongs to the correct LinearB organization.
    – Ensure it is sent in the Authorization: Bearer <your_api_token> header.
Advanced troubleshooting (problem → cause → fix)
Problem Cause Fix
Metric not stored The request failed validation.
Common issues:
  • Missing metric_name or timestamp.
  • Invalid timestamp format.
  • Non-numeric value when a number is expected downstream.
 Check the HTTP status and any error details in the response body.
Correct the payload and resend.
Metric does not show up where expected The metric name is not referenced by the target report/view,
or the time range does not include the metric’s timestamp. 		Confirm the report is configured to pull metric_name you are sending.
Adjust time filters so they include the metric’s timestamp.
Values look inconsistent Multiple metrics are being sent with the same name but different semantics
(for example, mixing percentages and raw counts). 		Standardize your integration so each metric_name has a clear, consistent meaning and value type.
If needed, split into separate metrics (for example, build_success_rate vs build_count).

FAQ

Can I send metrics without a value?

Yes. value is optional, but most use cases send a numeric value so the metric can be charted or aggregated.

Can I attach multiple entities to the same metric?

Yes. The entity object can include more than one supported field (for example, both pr_url and commit_sha).

What are tags used for?

tags are arbitrary key/value pairs that help you group, filter, or categorize metrics later (for example, "environment": "staging" or "tool": "coverage-service").

Is this the same as Measurements v2?

No. External Custom Metrics is focused on entity-scoped metrics (PR, repo, commit, contributor). Measurements v2 is designed for more general time-series metrics at the team, service, or org level.

For additional information, please visit our external API documentation

For additional technical support, please contact LinearB support.

How did we do?

API - Deployment

API - Incidents

Contact