Multiple Metrics

Retrieve multiple metrics in a single API request

Get Multiple Metrics

The get-multiple-metrics endpoint allows you to retrieve multiple different metrics in a single API request, which is useful for dashboards and reports.

Endpoint: POST /metrics/v2/get-multiple-metrics

Authentication Required: Yes

Request Format

{
  "filters": {
    "key1": "value1",
    "key2": "value2"
  },
  "group_by": ["field1", "field2"],
  "date_level": "day|week|month|quarter|year",
  "metrics": ["metric1", "metric2", "metric3"],
  "metric_min_values": {
    "metric1": 0,
    "metric2": 0,
    "metric3": 0
  },
  "date_fields": {
    "metric1": "created_at",
    "metric2": "merged_at",
    "metric3": "completed_at"
  },
  "aggregations": {
    "metric1": "sum",
    "metric2": "avg",
    "metric3": "count"
  },
  "include_previous_period": false
}

Parameter Details

metrics

array

required

Array of metric types to retrieve. You can include any of the available metrics from the different categories.

Example: ["cycle-time", "pull-requests-count", "completed-issues-count"]

metric_min_values

object

Object mapping each metric to its minimum value threshold.

Example:

{
  "cycle-time": 0,
  "pull-requests-count": 1,
  "completed-issues-count": 0
}

date_fields

object

Object mapping each metric to the date field to use for time-based calculations.

Example:

{
  "cycle-time": "merged_at",
  "pull-requests-count": "created_at",
  "completed-issues-count": "completed_at"
}

aggregations

object

Object mapping each metric to the aggregation method to use.

Example:

{
  "cycle-time": "avg",
  "pull-requests-count": "sum",
  "completed-issues-count": "sum"
}

Response Format

The response contains an array of results, with each result including the metric name, value, and group by values:

{
  "results": [
    {
      "metric_name": "cycle-time",
      "value": 16.4,
      "group_by": {
        "repository_name": "repo-a"
      },
      "unit": "hours"
    },
    {
      "metric_name": "pull-requests-count",
      "value": 42,
      "group_by": {
        "repository_name": "repo-a"
      }
    },
    {
      "metric_name": "completed-issues-count",
      "value": 38,
      "group_by": {
        "repository_name": "repo-a"
      }
    },
    {
      "metric_name": "cycle-time",
      "value": 12.8,
      "group_by": {
        "repository_name": "repo-b"
      },
      "unit": "hours"
    },
    {
      "metric_name": "pull-requests-count",
      "value": 36,
      "group_by": {
        "repository_name": "repo-b"
      }
    },
    {
      "metric_name": "completed-issues-count",
      "value": 29,
      "group_by": {
        "repository_name": "repo-b"
      }
    }
  ],
  "meta": {
    "filters": {
      "start_date": "2023-01-01",
      "end_date": "2023-12-31"
    },
    "date_range": {
      "start_date": "2023-01-01",
      "end_date": "2023-12-31"
    }
  }
}

Example: Team Performance Dashboard

This example demonstrates retrieving multiple metrics for a team performance dashboard:

Request

curl -X POST 'https://api.bilanc.co/metrics/v2/get-multiple-metrics' \
  -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": {
      "team_id": "team123",
      "start_date": "2023-01-01",
      "end_date": "2023-12-31"
    },
    "group_by": ["user_name"],
    "date_level": "month",
    "metrics": ["cycle-time", "pull-requests-count", "completed-issues-count"],
    "metric_min_values": {
      "cycle-time": 0,
      "pull-requests-count": 0,
      "completed-issues-count": 0
    },
    "date_fields": {
      "cycle-time": "merged_at",
      "pull-requests-count": "created_at",
      "completed-issues-count": "completed_at"
    },
    "aggregations": {
      "cycle-time": "avg",
      "pull-requests-count": "sum",
      "completed-issues-count": "sum"
    },
    "include_previous_period": true
  }'

Example: Repository Comparison

This example demonstrates retrieving multiple metrics to compare different repositories:

Request

curl -X POST 'https://api.bilanc.co/metrics/v2/get-multiple-metrics' \
  -H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": {
      "repository_id": ["repo1", "repo2", "repo3"],
      "start_date": "2023-01-01",
      "end_date": "2023-12-31"
    },
    "group_by": ["repository_name"],
    "date_level": "quarter",
    "metrics": ["cycle-time", "pull-requests-size", "complexity-score"],
    "metric_min_values": {
      "cycle-time": 0,
      "pull-requests-size": 0,
      "complexity-score": 0
    },
    "date_fields": {
      "cycle-time": "merged_at",
      "pull-requests-size": "created_at",
      "complexity-score": "created_at"
    },
    "aggregations": {
      "cycle-time": "median",
      "pull-requests-size": "avg",
      "complexity-score": "avg"
    },
    "time_series_data": true
  }'

Best Practices

1. Limit the number of metrics: Request only the metrics you need to avoid performance issues.
2. Use consistent date fields: When possible, use the same date field for related metrics.
3. Choose appropriate aggregations: Different metrics may require different aggregation methods.
4. Consider using time series data: For dashboard visualizations, setting time_series_data to true provides data formatted for charts.
5. Include previous period data: Setting include_previous_period to true provides comparison data for trend analysis.