Add Dedicated Runs Statistics API Endpoint

[okt-limonikas]

Problem

Currently, the runs statistics view (e.g., /runs?mode=charts&calendarMode=duration) requires fetching all runs via GET /api/v2/runs/ and performing client-side aggregation.

This approach has significant performance issues:

• Backend overload: The endpoint returns complete run objects with all fields, creating unnecessary database load
• Slow response times: Users experience delays while waiting for all runs data to be fetched and processed

The aggregation logic is currently implemented in libs/bublik/features/runs/src/lib/runs-stats in the UI repository.

Solution

Introduce a dedicated /api/v2/runs/stats/charts endpoint that performs server-side aggregation and returns pre-computed statistics.
Do know if path is good, check it

Endpoint Design

GET /api/v2/runs/stats/charts

Query Parameters:

• start_date (optional): Start date for the period (ISO 8601 format)
• finish_date (optional): End date for the period (ISO 8601 format)
• Additional filters matching existing /api/v2/runs/ parameters (branch, tags, etc.)

References

• Current UI aggregation logic: https://github.com/ts-factory/bublik-ui/tree/main/libs/bublik/features/runs/src/lib/runs-stats
• Example statistics view: https://ts-factory.io/bublik/v2/runs?mode=charts&calendarMode=duration&startDate=2025-07-22&finishDate=2026-01-22&duration=P0Y6M0DT0H0M0S&page=1

[ol-zayatsm]

Contract proposal for Runs Statistics API Endpoint

Endpoint Design

GET /api/v2/runs/charts

Query Parameters:

• group_by: day | week (by default day)
• Standard filters: start_date, finish_date, branch_expr, tag_expr, project

Response format(JSON):

{
  "results": [
    {
      "date": "2026-01-19T00:00:00Z",
      "ok": 15,
      "error": 2,
      "warning": 1,
      "busy": 0,
      "compromised": 0,
      "running": 1,
      "stopped": 0,
      "total": 19,
      "nok": 3,
      "passrate": 78.95,
      "ids": "101,102,103,..."
    }
  ],
  "present_statuses": ["ok", "error", "warning", "running"]
}

The proposed contract will allow the calculations to be completely transferred to the database side and reduce the amount of data transferred.

[okt-limonikas]

API

Query Parameters

• group_by: day | week (default: day)
• start_date: ISO 8601
• finish_date: ISO 8601
• tag_expr: string
• run_data: string
• branch_expr: string
• project: number

Response Shape (bucket)

{
  "date": "2026-01-19T00:00:00Z",
  "tests": {
    "ok": 245,
    "nok": 12,
    "total": 257,
    "passrate": 95.33
  },
  "run_ids_by_status": {
    "run-ok": [101, 102],
    "run-error": [103],
    "run-warning": [],
    "run-running": [],
    "run-compromised": [],
    "run-busy": [],
    "run-stopped": [],
    "run-interrupted": []
  }
}

Why

• run_ids_by_status is the single source of truth for status presence and counts.
• run_ids and present_statuses are dropped because they are derivable
• tests groups test stats to avoid ambiguous top-level keys.

Example: group_by=day

{
  "buckets": [
    {
      "date": "2026-01-19T00:00:00Z",
      "tests": {
        "ok": 245,
        "nok": 12,
        "total": 257,
        "passrate": 95.33
      },
      "run_ids_by_status": {
        "run-ok": [101,102],
        "run-error": [103],
        "run-warning": [],
        "run-running": [],
        "run-compromised": [],
        "run-busy": [],
        "run-stopped": [],
        "run-interrupted": []
      }
    }
  ]
}

Logic

• date: bucket start in UTC:
  • group_by=day: start of day (00:00:00Z)
  • group_by=week: start of week (00:00:00Z, ISO week start Monday)
• tests.ok, tests.nok, tests.total - test counts
• tests.passrate: percentage
• run_ids_by_status: map of RUN_STATUS => list of run IDs in this bucket
  RUN_STATUS keys

Must match UI enum values:

• run-ok
• run-error
• run-warning
• run-running
• run-compromised
• run-busy
• run-stopped
• run-interrupted

Example: group_by=week

{
  "buckets": [
    {
      "date": "2026-01-19T00:00:00Z",
      "tests": {
        "ok": 515,
        "nok": 42,
        "total": 557,
        "passrate": 92.46
      },
      "run_ids_by_status": {
        "run-ok": [101,102,104,106],
        "run-error": [103],
        "run-warning": [105],
        "run-running": [],
        "run-compromised": [],
        "run-busy": [],
        "run-stopped": [],
        "run-interrupted": []
      }
    },
    {
      "date": "2026-01-26T00:00:00Z",
      "tests": {
        "ok": 610,
        "nok": 30,
        "total": 640,
        "passrate": 95.31
      },
      "run_ids_by_status": {
        "run-ok": [107,108],
        "run-error": [],
        "run-warning": [],
        "run-running": [109],
        "run-compromised": [],
        "run-busy": [],
        "run-stopped": [],
        "run-interrupted": []
      }
    }
  ]
}