> ## Documentation Index
> Fetch the complete documentation index at: https://bilanc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Benchmark Metrics

> API endpoints for comparing your metrics against industry benchmarks

## Benchmark Metrics

Benchmark metrics provide insights into how your engineering organization compares to industry standards and best practices.

### Available Metrics

<ParamField path="benchmark" type="string">
  Retrieves benchmark metrics for comparison
</ParamField>

## Benchmark Metric

This endpoint compares a given metric against anonymized data from all organizations on the platform.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST 'https://api.bilanc.co/metrics/benchmark' \
    -H 'Authorization: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "filters": {
        "start_date": "2023-01-01",
        "end_date": "2023-12-31"
      },
      "benchmark_metric": "cycle-time",
      "date_field": "merged_at"
    }'
  ```

  ```json Response theme={null}
  {
    "results": [
      {
        "metric_name": "cycle-time",
        "value": 16.4,
        "benchmark_value": 22.5,
        "benchmark_p25": 12.8,
        "benchmark_p50": 22.5,
        "benchmark_p75": 35.2,
        "percentile": 38,
        "unit": "hours"
      },
      {
        "metric_name": "pickup-time",
        "value": 3.2,
        "benchmark_value": 4.5,
        "benchmark_p25": 2.1,
        "benchmark_p50": 4.5,
        "benchmark_p75": 8.3,
        "percentile": 42,
        "unit": "hours"
      },
      {
        "metric_name": "review-time",
        "value": 6.8,
        "benchmark_value": 9.2,
        "benchmark_p25": 5.5,
        "benchmark_p50": 9.2,
        "benchmark_p75": 14.1,
        "percentile": 35,
        "unit": "hours"
      }
    ],
    "meta": {
      "filters": {
        "start_date": "2023-01-01",
        "end_date": "2023-12-31"
      }
    }
  }
  ```
</CodeGroup>

## PR Size Benchmark

Compare your organization's pull request size against the platform benchmark.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST 'https://api.bilanc.co/metrics/benchmark' \
    -H 'Authorization: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "filters": {
        "start_date": "2023-01-01",
        "end_date": "2023-12-31"
      },
      "benchmark_metric": "pull-requests-size",
      "date_field": "merged_at"
    }'
  ```

  ```json Response theme={null}
  {
    "results": [
      {
        "metric_name": "pull-requests-size",
        "value": 120.5,
        "benchmark_p25": 85.0,
        "benchmark_p50": 145.0,
        "benchmark_p75": 220.0,
        "percentile": 42,
        "unit": "lines"
      }
    ],
    "meta": {
      "filters": {
        "start_date": "2023-01-01",
        "end_date": "2023-12-31"
      }
    }
  }
  ```
</CodeGroup>

## Parameter Notes

<ResponseField name="benchmark_metric" type="string" required>
  The metric to benchmark (e.g. `cycle-time`, `pull-requests-size`, `pickup-time`). This is a top-level request body parameter, not a filter.
</ResponseField>

<ResponseField name="date_field" type="string" required>
  The date field to use for the benchmark query (e.g. `merged_at`, `created_at`).
</ResponseField>

<ResponseField name="filters" type="object">
  Standard date filters apply:

  * `start_date`: Start of the date range (required)
  * `end_date`: End of the date range (defaults to today)
</ResponseField>

<ResponseField name="benchmark_metadata" type="object">
  The response includes benchmark metadata:

  * `benchmark_value`: The median value for the benchmark group
  * `benchmark_p25`: The 25th percentile value
  * `benchmark_p50`: The 50th percentile value (median)
  * `benchmark_p75`: The 75th percentile value
  * `percentile`: Your organization's percentile ranking
</ResponseField>

## Common Use Cases

* **Performance Comparison**: Compare your team's performance against industry standards
* **Goal Setting**: Set realistic goals based on industry benchmarks
* **Identifying Opportunities**: Find areas where your team significantly underperforms compared to benchmarks
* **Executive Reporting**: Provide context for metrics by showing where the organization stands relative to peers
* **Competitive Analysis**: Understand how your engineering organization compares to competitors