> ## 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.
# 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).
```http theme={null}
Authorization: YOUR_API_KEY
```
You can generate an API key from your [Bilanc dashboard](https://app.bilanc.co) 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:
```json theme={null}
{
"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
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 |
Fields to group results by. Default: `[]`
Common values: `team_name`, `team_id`, `repository_name`, `name` (author), `manager_name`, `department`, `squad_name`, `squad_level`, `role`
Time granularity for aggregation. Options: `day`, `week`, `month`, `quarter`, `year`. Omit to return a single aggregate row.
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.
Exclude rows where the metric value is below this threshold. Default: `0`.
Which date column to use for time-based filtering and grouping. Available values depend on the metric — see each metric page for valid options.
When `true`, returns data formatted for chart libraries (series + categories). Default: `false`.
When `true`, includes the equivalent previous period for comparison. Results include a `previous_*` field alongside the current value. Default: `false`.
Field name to sort results by.
Sort direction: `ASC` or `DESC`. Default: `ASC`.
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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
* `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-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
* `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-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-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
* `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