@celigo/api-specs 0.2.104 → 0.2.106

package/dist/flow.yml

@@ -892,6 +892,110 @@ paths:
           $ref: '#/components/responses/404-not-found'
         '422':
           $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/flows/{_flowId}/runs/stats:
+    post:
+      x-internal: false
+      operationId: getFlowRuntimeChartStats
+      tags:
+        - Flows
+      summary: Get flow runtime chart stats
+      description: |-
+        Returns historical runtime statistics and chart buckets for a single flow.
+        Used by the proactive alerts UI to suggest and preview long-runtime
+        thresholds.
+
+        This is not the job-dashboard aggregate API. Dashboard totals live at
+        `POST /v1/flows/runs/stats` (job spec). This path is
+        `POST /v1/flows/{_flowId}/runs/stats`.
+
+        Requires the proactive alerts feature flag and ClickHouse to be enabled for
+        the user. When ClickHouse is unavailable, returns
+        `{ "clickhouseAvailable": false }`.
+
+        Time range constraints:
+        - `startTime` is required (ISO 8601 UTC)
+        - `endTime` defaults to now when omitted
+        - Minimum range: 1 hour
+        - Maximum range: 90 days
+        - Granularity: hourly buckets for ranges ≤ 24h; daily buckets for longer ranges
+
+        Chart `alertsTriggered` / `totalAlertsTriggered` count completed runs whose
+        runtime is **strictly greater than** the threshold used for the query.
+        That is a historical chart count, not the number of alert emails sent.
+      parameters:
+        - name: _flowId
+          in: path
+          required: true
+          description: Flow id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: flows
+            examples:
+              - 507f1f77bcf86cd799439011
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/FlowRunsStatsRequest'
+            examples:
+              default:
+                value:
+                  type: runtimeSummary
+                  startTime: '2026-05-01T00:00:00.000Z'
+                  endTime: '2026-06-01T00:00:00.000Z'
+                  thresholdMinutes: 45
+      responses:
+        '200':
+          description: Runtime summary, empty-state payload, or ClickHouse-unavailable marker.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FlowRunsStatsResponse'
+              examples:
+                summary:
+                  summary: Runtime summary with chart buckets
+                  value:
+                    _flowId: 507f1f77bcf86cd799439011
+                    startTime: '2026-05-01T00:00:00.000Z'
+                    endTime: '2026-06-01T00:00:00.000Z'
+                    granularity: day
+                    thresholdMinutes: 45
+                    totalRuns: 120
+                    totalAlertsTriggered: 8
+                    emptyState: false
+                    truncated: false
+                    statistics:
+                      suggestedThreshold: 45
+                    chartEntries:
+                      - bucket: '2026-05-01'
+                        totalRuns: 10
+                        alertsTriggered: 1
+                        avgRuntimeMinutes: 22.5
+                        p5RuntimeMinutes: 5
+                        p95RuntimeMinutes: 60
+                emptyState:
+                  summary: Fewer than 3 completed runs
+                  value:
+                    _flowId: 507f1f77bcf86cd799439011
+                    startTime: '2026-05-01T00:00:00.000Z'
+                    endTime: '2026-06-01T00:00:00.000Z'
+                    emptyState: true
+                clickhouseUnavailable:
+                  summary: ClickHouse not available
+                  value:
+                    clickhouseAvailable: false
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
   /v1/flows/{_id}/traceKey:
     get:
       x-internal: false
@@ -6151,6 +6255,166 @@ components:
             error:
               type: string
               description: Human-readable reason the run was not started.
+    FlowRunsStatsRequest:
+      type: object
+      required:
+        - type
+        - startTime
+      properties:
+        type:
+          type: string
+          description: Request type.
+          enum:
+            - runtimeSummary
+          x-enumDescriptions:
+            runtimeSummary: Historical runtime summary and chart buckets for alert threshold preview.
+          examples:
+            - runtimeSummary
+        startTime:
+          type: string
+          format: date-time
+          description: Start of query window (ISO 8601 UTC). Must not be in the future.
+          examples:
+            - '2026-05-01T00:00:00.000Z'
+        endTime:
+          type: string
+          format: date-time
+          description: End of query window (ISO 8601 UTC). Defaults to now. Must not be in the future.
+          examples:
+            - '2026-06-01T00:00:00.000Z'
+        thresholdMinutes:
+          type: integer
+          minimum: 5
+          maximum: 59940
+          description: |-
+            Optional threshold override in minutes. When omitted, the response uses
+            `statistics.suggestedThreshold` (ceil of p99 runtime, floored at 5).
+            Chart counts use this value with a strict greater-than comparison.
+          examples:
+            - 45
+    FlowRunsStatsResponse:
+      type: object
+      description: |-
+        Runtime statistics response for the proactive alert threshold chart.
+
+        Three shapes are possible:
+        - **Summary** — `emptyState: false` with `statistics`, `chartEntries`, and
+          run totals. Returned when the time range has 3 or more completed runs.
+        - **Empty state** — `{ _flowId, startTime, endTime, emptyState: true }` with
+          no chart data. Returned when the time range has fewer than 3 completed
+          runs.
+        - **ClickHouse unavailable** — only `clickhouseAvailable: false`. Returned
+          when ClickHouse is not enabled for the caller.
+      properties:
+        _flowId:
+          type: string
+          format: objectId
+          x-celigo-refModel: flows
+          description: Echoed flow id.
+          examples:
+            - 507f1f77bcf86cd799439011
+        startTime:
+          type: string
+          format: date-time
+          description: Echoed query start time.
+          examples:
+            - '2026-05-01T00:00:00.000Z'
+        endTime:
+          type: string
+          format: date-time
+          description: Echoed query end time.
+          examples:
+            - '2026-06-01T00:00:00.000Z'
+        granularity:
+          type: string
+          description: Bucket granularity for chart entries. Absent on empty-state and ClickHouse-unavailable responses.
+          enum:
+            - hour
+            - day
+          x-enumDescriptions:
+            hour: Hourly buckets (ranges ≤ 24h).
+            day: Daily buckets (ranges longer than 24h).
+        thresholdMinutes:
+          type: integer
+          description: Threshold used for chart alert-count computation. Absent on empty-state and ClickHouse-unavailable responses.
+          examples:
+            - 45
+        totalRuns:
+          type: integer
+          description: Total completed runs in the time range. Absent on empty-state and ClickHouse-unavailable responses.
+          examples:
+            - 120
+        totalAlertsTriggered:
+          type: integer
+          description: |-
+            Count of completed runs in the window whose runtime is strictly greater
+            than `thresholdMinutes`. Historical chart metric only — not the number
+            of alert emails sent. Absent on empty-state and ClickHouse-unavailable
+            responses.
+          examples:
+            - 8
+        emptyState:
+          type: boolean
+          description: |-
+            `true` when the time range has fewer than 3 completed runs (no chart
+            data). `false` on summary responses. Absent on ClickHouse-unavailable
+            responses.
+          examples:
+            - false
+        truncated:
+          type: boolean
+          description: |-
+            True when totalRuns exceeds 5000. Indicates a high-volume warning; chart
+            data is still complete for the requested time range. Absent on
+            empty-state and ClickHouse-unavailable responses.
+          examples:
+            - false
+        clickhouseAvailable:
+          type: boolean
+          description: |-
+            Present only when ClickHouse is not available for the caller. Value is
+            always `false` when present. Absent on successful summary and
+            empty-state responses.
+          examples:
+            - false
+        statistics:
+          type: object
+          description: |-
+            Present on successful summary responses. Used by the UI for the
+            suggested threshold hint. Absent on empty-state and
+            ClickHouse-unavailable responses.
+          properties:
+            suggestedThreshold:
+              type: integer
+              description: |-
+                Suggested threshold in minutes: ceil of the p99 completed-run
+                runtime in the window, then floored at the platform minimum (5).
+              examples:
+                - 45
+        chartEntries:
+          type: array
+          description: |-
+            Chart data buckets. Present on successful summary responses. Absent on
+            empty-state and ClickHouse-unavailable responses.
+          items:
+            type: object
+            properties:
+              bucket:
+                type: string
+                description: ISO hourly timestamp or YYYY-MM-DD date.
+                examples:
+                  - '2026-05-01'
+              totalRuns:
+                type: integer
+              alertsTriggered:
+                type: integer
+                description: Completed runs in this bucket with runtime strictly greater than the query threshold.
+              avgRuntimeMinutes:
+                type: number
+              p5RuntimeMinutes:
+                type: number
+              p95RuntimeMinutes:
+                type: number
     FlowTraceKeyResponse:
       type: array
       description: |-
@@ -8179,5 +8443,18 @@ components:
                 errors:
                   - code: dependencies_not_deleted
                     message: export 6902d88c10b42b2eaac9b2a1 must be deleted before you can delete connection 6398ddf316be761fb16a6523
+    403-forbidden:
+      description: |
+        Forbidden. The authenticated caller does not have permission to perform this operation.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: forbidden
+                    message: You do not have permission to access this resource.
 x-enable-proxy: true
 x-internal: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.104",
+  "version": "0.2.106",
   "private": false,
   "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
   "keywords": [

package/schemas.json

@@ -1,8 +1,8 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "34353c5a",
-		"generatedAt": "2026-10-12"
+		"iasCommit": "2ab2e845",
+		"generatedAt": "2026-10-13"
 	},
 	"roots": {
 		"aiagent": 133,