Metrics Overview

Overview of the metrics endpoint structure and common parameters

Metrics Endpoint Structure

All metrics endpoints follow the same base structure:

Endpoint: POST /metrics/{metric_type}

Authentication Required: Yes — API key passed directly in the Authorization header (no Bearer prefix).

Authorization: YOUR_API_KEY

You can generate an API key from your Bilanc dashboard under Settings → API Keys.

Path Parameters:

• metric_type (string, required): The type of metric to retrieve. See available metric types below.

Common Request Parameters

Most metric endpoints accept the following request parameters:

{
  "filters": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "member": ["user-id-1"],
    "team": ["team-id-1"],
    "repositories": [{"repository_name": "my-repo"}]
  },
  "group_by": ["team_name", "repository_name"],
  "date_level": "day|week|month|quarter|year",
  "aggregation": "SUM|AVG|MIN|MAX",
  "metric_min_value": 0,
  "date_field": "created_at|merged_at|completed_at",
  "time_series_data": false,
  "include_previous_period": false,
  "order_by": "team_name",
  "order_direction": "ASC",
  "limit": 50
}

Parameter Details

filters · object · required

Object containing all filter criteria. start_date is required for most metrics.

Filter	Type	Description
start_date	string	Start of the date range (ISO 8601, e.g. 2024-01-01)
end_date	string	End of the date range. Defaults to today if omitted
member	string[]	Filter by author/contributor merged user IDs
team	string[]	Filter by team IDs
squad_ids	string[]	Filter by squad IDs
squad_levels	integer[]	Filter by squad hierarchy level
manager_ids	string[]	Filter by manager user IDs
repositories	object[]	Array of {"repository_name": "..."} objects
departments	string[]	Filter by department names
locations	string[]	Filter by employee location
levels	string[]	Filter by employee level
source_types	string[]	Filter by integration source type (e.g. github, jira)
pr_states	string[]	PR states: open, closed, merged
pr_categories	string[]	PR category classifications
pr_ids	string[]	Filter by specific PR IDs
associated_pr_ids	string[]	Filter by associated PR IDs
pull_requests_search_term	string	Full-text search across PR title, description, body, summary, and category
sources	string[]	VCS source: github, gitlab, bitbucket
branches	string[]	Filter by git branch names
review_hour_of_day	integer[]	Filter reviews by hour of day (0–23)
review_rounds_bucket	string[]	Filter by review rounds bucket
ticket_status	string[]	Issue states: completed, started, backlog, etc.
issue_ids	string[]	Filter by specific issue IDs
project_ids	string[]	Filter by project IDs
workflow_run_ids	string[]	Filter by GitHub Actions workflow run IDs
workflow_names	string[]	Filter by workflow names
run_conclusions	string[]	Workflow conclusions: success, failure, cancelled, etc.
ai_copilot_sources	string[]	Filter by AI copilot source name

group_by · string[]

Fields to group results by. Default: []

Common values: team_name, team_id, repository_name, name (author), manager_name, department, squad_name, squad_level, role

date_level · string

Time granularity for aggregation. Options: day, week, month, quarter, year. Omit to return a single aggregate row.

aggregation · string

Aggregation method. Required for non-count metrics. Options: SUM, AVG, MIN, MAX. Count-based metrics (e.g. pull-requests-count, issues-count) do not require this field.

metric_min_value · number

Exclude rows where the metric value is below this threshold. Default: 0.

date_field · string

Which date column to use for time-based filtering and grouping. Available values depend on the metric — see each metric page for valid options.

time_series_data · boolean

When true, returns data formatted for chart libraries (series + categories). Default: false.

include_previous_period · boolean

When true, includes the equivalent previous period for comparison. Results include a previous_* field alongside the current value. Default: false.

order_by · string

Field name to sort results by.

order_direction · string

Sort direction: ASC or DESC. Default: ASC.

limit · integer

Maximum number of rows to return (1–200).

Response Format

The response format depends on the requested metric and parameters. By default, the API returns a JSON object with the requested metric data:

{
  "results": [
    {
      "metric_name": "pull-requests-count",
      "value": 42,
      "group_by": {
        "repository_name": "my-repository"
      }
    },
    {
      "metric_name": "pull-requests-count",
      "value": 18,
      "group_by": {
        "repository_name": "another-repository"
      }
    }
  ],
  "meta": {
    "filters": {
      "start_date": "2023-01-01",
      "end_date": "2023-12-31"
    },
    "date_range": {
      "start_date": "2023-01-01",
      "end_date": "2023-12-31"
    }
  }
}

If time_series_data is set to true, the response will be formatted for line chart visualization:

{
  "series": [
    {
      "name": "my-repository",
      "data": [4, 8, 12, 10, 8]
    },
    {
      "name": "another-repository",
      "data": [2, 4, 5, 4, 3]
    }
  ],
  "categories": ["Jan 2023", "Feb 2023", "Mar 2023", "Apr 2023", "May 2023"],
  "meta": {
    "filters": {
      "start_date": "2023-01-01",
      "end_date": "2023-05-31"
    },
    "date_range": {
      "start_date": "2023-01-01",
      "end_date": "2023-05-31"
    }
  }
}

Available Metric Types

The API provides a wide range of metric types across several categories:

Development Metrics

• coding-time: Time spent coding
• pickup-time: Time between commit and PR open
• commit-to-open: Time from commit to PR open
• open-to-review: Time between PR open and first review
• review-to-merge: Time between first review and merge
• review-time: Total time spent in review
• rework-time: Time spent on rework after review
• cycle-time: Full cycle time from commit to merge
• time-to-first-comment: Time to the first comment on a PR
• rework-rate: Rate of rework after review
• complexity-score: Code complexity score
• contributors-count: Number of unique contributors

Pull Request Metrics

• pull-requests-count: Number of pull requests
• pull-requests-size: Size of pull requests (lines of code)
• review-rate: Percentage of PRs that receive a review
• reviews-count: Number of reviews submitted
• review-interactions-count: Number of review interactions
• review-rounds: Number of review rounds per PR
• reviewers-per-pr: Average number of reviewers per PR
• active-reviewers: Number of active reviewers
• changes-requested-rate: Rate of change-request reviews
• comment-interactions-count: Comment interaction count
• comments-count: Number of comments
• comments-per-pr: Average comments per PR
• commit-interactions-count: Commit interaction count
• commits-count: Number of commits

Issue Metrics

• issues-count: Number of issues
• completed-issues-count: Number of completed issues
• started-issues-count: Number of started issues
• backlog-issues-count: Number of backlog issues
• story-points: Story points
• completed-story-points: Completed story points
• started-story-points: Started story points
• issue-cycle-time: Time from issue creation to completion
• issue-comment-interactions-count: Issue comment interaction count
• issue-comments-count: Number of issue comments

AI Copilot Metrics

• ai-adoption-rate: AI tool adoption rate
• ai-acceptance-rate: Rate of accepted AI suggestions
• ai-total-loc: Total lines of code written with AI
• ai-percent-ai-generated-code: Percentage of AI-generated code
• ai-complexity-score: Complexity score of AI-assisted code
• accepted-lines: Lines accepted from AI suggestions
• suggested-lines: Lines suggested by AI
• chat-requests: Number of AI chat requests
• composer-requests: Number of AI composer requests
• agent-requests: Number of AI agent requests
• cmd-k-usages: Number of Cmd+K usages
• most-used-programming-language: Most used programming language with AI
• adopted-users: Number of users who adopted AI tools
• acceptance-rate: AI suggestion acceptance rate
• adoption-rate: AI tool adoption rate
• total-lines-added: Total lines added with AI assistance
• total-lines-deleted: Total lines deleted with AI assistance
• total-accepts: Total accepted AI suggestions
• total-rejects: Total rejected AI suggestions
• ai-total-token-usage: Total AI token usage
• ai-total-cost: Total AI cost
• ai-favourite-model: Most used AI model
• ai-pr-count: Number of PRs created with AI assistance
• ai-code-ratio: Ratio of AI-generated to total code

Workflow Metrics

• workflow-runs-count: Number of CI/CD workflow runs
• workflow-run-duration: Average workflow run duration
• workflow-run-duration-p95: 95th percentile workflow run duration
• workflow-run-success-rate: Workflow run success rate
• artifact-sizes: Size of build artifacts
• estimated-workflow-run-cost: Estimated cost of workflow runs

Other Metrics

• releases-count: Number of releases
• users-count: Number of active users
• benchmark: Compare metrics against industry benchmarks
• get-multiple-metrics: Retrieve multiple metrics in a single request
• date-details: Date range metadata