openapi: 3.0.3
info:
  title: PostHog actions alerts API
  version: 1.0.0
  description: ''
tags:
- name: alerts
paths:
  /api/environments/{environment_id}/alerts/:
    get:
      operationId: environments_alerts_list
      parameters:
      - $ref: '#/components/parameters/EnvironmentIdPath'
      - name: limit
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: offset
        required: false
        in: query
        description: The initial index from which to return the results.
        schema:
          type: integer
      tags:
      - alerts
      security:
      - PersonalAPIKeyAuth:
        - alert:read
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedAlertList'
          description: ''
      deprecated: true
      x-explicit-tags: []
    post:
      operationId: environments_alerts_create
      parameters:
      - $ref: '#/components/parameters/EnvironmentIdPath'
      tags:
      - alerts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Alert'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Alert'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Alert'
        required: true
      security:
      - PersonalAPIKeyAuth:
        - alert:write
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
          description: ''
      deprecated: true
      x-explicit-tags: []
  /api/environments/{environment_id}/alerts/{id}/:
    get:
      operationId: environments_alerts_retrieve
      parameters:
      - in: query
        name: checks_date_from
        schema:
          type: string
        description: Relative date string for the start of the check history window (e.g. '-24h', '-7d', '-14d'). Returns checks created after this time. Max retention is 14 days.
      - in: query
        name: checks_date_to
        schema:
          type: string
        description: Relative date string for the end of the check history window (e.g. '-1h', '-1d'). Defaults to now if not specified.
      - in: query
        name: checks_limit
        schema:
          type: integer
        description: Maximum number of check results to return (default 5, max 500). Applied after date filtering.
      - in: query
        name: checks_offset
        schema:
          type: integer
        description: Number of newest checks to skip (0-based). Use with checks_limit for pagination. Default 0.
      - $ref: '#/components/parameters/EnvironmentIdPath'
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this alert configuration.
        required: true
      tags:
      - alerts
      security:
      - PersonalAPIKeyAuth:
        - alert:read
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
          description: ''
      deprecated: true
      x-explicit-tags: []
    put:
      operationId: environments_alerts_update
      parameters:
      - $ref: '#/components/parameters/EnvironmentIdPath'
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this alert configuration.
        required: true
      tags:
      - alerts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Alert'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Alert'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Alert'
        required: true
      security:
      - PersonalAPIKeyAuth:
        - alert:write
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
          description: ''
      deprecated: true
      x-explicit-tags: []
    patch:
      operationId: environments_alerts_partial_update
      parameters:
      - $ref: '#/components/parameters/EnvironmentIdPath'
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this alert configuration.
        required: true
      tags:
      - alerts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedAlert'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedAlert'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedAlert'
      security:
      - PersonalAPIKeyAuth:
        - alert:write
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
          description: ''
      deprecated: true
      x-explicit-tags: []
    delete:
      operationId: environments_alerts_destroy
      parameters:
      - $ref: '#/components/parameters/EnvironmentIdPath'
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this alert configuration.
        required: true
      tags:
      - alerts
      security:
      - PersonalAPIKeyAuth:
        - alert:write
      responses:
        '204':
          description: No response body
      deprecated: true
      x-explicit-tags: []
  /api/environments/{environment_id}/alerts/simulate/:
    post:
      operationId: environments_alerts_simulate_create
      description: Simulate a detector on an insight's historical data. Read-only — no AlertCheck records are created.
      parameters:
      - $ref: '#/components/parameters/EnvironmentIdPath'
      tags:
      - alerts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertSimulate'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AlertSimulate'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AlertSimulate'
        required: true
      security:
      - PersonalAPIKeyAuth:
        - alert:read
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertSimulateResponse'
          description: ''
      deprecated: true
      x-explicit-tags: []
  /api/projects/{project_id}/alerts/:
    get:
      operationId: alerts_list
      parameters:
      - name: limit
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: offset
        required: false
        in: query
        description: The initial index from which to return the results.
        schema:
          type: integer
      - $ref: '#/components/parameters/ProjectIdPath'
      tags:
      - alerts
      security:
      - PersonalAPIKeyAuth:
        - alert:read
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedAlertList'
          description: ''
      x-explicit-tags: []
    post:
      operationId: alerts_create
      parameters:
      - $ref: '#/components/parameters/ProjectIdPath'
      tags:
      - alerts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Alert'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Alert'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Alert'
        required: true
      security:
      - PersonalAPIKeyAuth:
        - alert:write
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
          description: ''
      x-explicit-tags: []
  /api/projects/{project_id}/alerts/{id}/:
    get:
      operationId: alerts_retrieve
      parameters:
      - in: query
        name: checks_date_from
        schema:
          type: string
        description: Relative date string for the start of the check history window (e.g. '-24h', '-7d', '-14d'). Returns checks created after this time. Max retention is 14 days.
      - in: query
        name: checks_date_to
        schema:
          type: string
        description: Relative date string for the end of the check history window (e.g. '-1h', '-1d'). Defaults to now if not specified.
      - in: query
        name: checks_limit
        schema:
          type: integer
        description: Maximum number of check results to return (default 5, max 500). Applied after date filtering.
      - in: query
        name: checks_offset
        schema:
          type: integer
        description: Number of newest checks to skip (0-based). Use with checks_limit for pagination. Default 0.
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this alert configuration.
        required: true
      - $ref: '#/components/parameters/ProjectIdPath'
      tags:
      - alerts
      security:
      - PersonalAPIKeyAuth:
        - alert:read
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
          description: ''
      x-explicit-tags: []
    put:
      operationId: alerts_update
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this alert configuration.
        required: true
      - $ref: '#/components/parameters/ProjectIdPath'
      tags:
      - alerts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Alert'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Alert'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Alert'
        required: true
      security:
      - PersonalAPIKeyAuth:
        - alert:write
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
          description: ''
      x-explicit-tags: []
    patch:
      operationId: alerts_partial_update
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this alert configuration.
        required: true
      - $ref: '#/components/parameters/ProjectIdPath'
      tags:
      - alerts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedAlert'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedAlert'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedAlert'
      security:
      - PersonalAPIKeyAuth:
        - alert:write
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
          description: ''
      x-explicit-tags: []
    delete:
      operationId: alerts_destroy
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this alert configuration.
        required: true
      - $ref: '#/components/parameters/ProjectIdPath'
      tags:
      - alerts
      security:
      - PersonalAPIKeyAuth:
        - alert:write
      responses:
        '204':
          description: No response body
      x-explicit-tags: []
  /api/projects/{project_id}/alerts/simulate/:
    post:
      operationId: alerts_simulate_create
      description: Simulate a detector on an insight's historical data. Read-only — no AlertCheck records are created.
      parameters:
      - $ref: '#/components/parameters/ProjectIdPath'
      tags:
      - alerts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertSimulate'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AlertSimulate'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AlertSimulate'
        required: true
      security:
      - PersonalAPIKeyAuth:
        - alert:read
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertSimulateResponse'
          description: ''
      x-explicit-tags: []
components:
  schemas:
    AlertCondition:
      additionalProperties: false
      properties:
        type:
          $ref: '#/components/schemas/AlertConditionType'
      required:
      - type
      title: AlertCondition
      type: object
    CalculationIntervalEnum:
      enum:
      - hourly
      - daily
      - weekly
      - monthly
      type: string
      description: '* `hourly` - hourly

        * `daily` - daily

        * `weekly` - weekly

        * `monthly` - monthly'
    IQRDetectorConfig:
      additionalProperties: false
      properties:
        multiplier:
          default: null
          description: 'IQR multiplier for fence calculation (default: 1.5, use 3.0 for far outliers)'
          title: Multiplier
          type: number
          nullable: true
        preprocessing:
          default: null
          description: Preprocessing transforms applied before detection
          allOf:
          - $ref: '#/components/schemas/PreprocessingConfig'
          nullable: true
        type:
          default: iqr
          title: Type
          type: string
          enum:
          - iqr
        window:
          default: null
          description: 'Rolling window size for calculating quartiles (default: 30)'
          title: Window
          type: integer
          nullable: true
      title: IQRDetectorConfig
      type: object
    InvestigationInconclusiveActionEnum:
      enum:
      - notify
      - suppress
      type: string
      description: '* `notify` - Notify

        * `suppress` - Suppress'
    AlertCheckStateEnum:
      enum:
      - Firing
      - Not firing
      - Errored
      - Snoozed
      type: string
      description: '* `Firing` - Firing

        * `Not firing` - Not firing

        * `Errored` - Errored

        * `Snoozed` - Snoozed'
    InsightsThresholdBounds:
      additionalProperties: false
      properties:
        lower:
          default: null
          description: Alert fires when the value drops below this number.
          title: Lower
          type: number
          nullable: true
        upper:
          default: null
          description: Alert fires when the value exceeds this number.
          title: Upper
          type: number
          nullable: true
      title: InsightsThresholdBounds
      type: object
    EnsembleOperator:
      enum:
      - and
      - or
      title: EnsembleOperator
      type: string
    InvestigationStatusEnum:
      enum:
      - pending
      - running
      - done
      - failed
      - skipped
      type: string
      description: '* `pending` - pending

        * `running` - running

        * `done` - done

        * `failed` - failed

        * `skipped` - skipped'
    RoleAtOrganizationEnum:
      enum:
      - engineering
      - data
      - product
      - founder
      - leadership
      - marketing
      - sales
      - other
      type: string
      description: '* `engineering` - Engineering

        * `data` - Data

        * `product` - Product Management

        * `founder` - Founder

        * `leadership` - Leadership

        * `marketing` - Marketing

        * `sales` - Sales / Success

        * `other` - Other'
    Alert:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        created_by:
          allOf:
          - $ref: '#/components/schemas/UserBasic'
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        insight:
          type: integer
          description: 'Insight ID monitored by this alert. Note: Response returns full InsightBasicSerializer object.'
        name:
          type: string
          description: Human-readable name for the alert.
        subscribed_users:
          type: array
          items:
            type: integer
          description: 'User IDs to subscribe to this alert. Note: Response returns full UserBasicSerializer object.'
        threshold:
          allOf:
          - $ref: '#/components/schemas/Threshold'
          description: Threshold configuration with bounds and type for evaluating the alert.
        condition:
          allOf:
          - $ref: '#/components/schemas/AlertCondition'
          nullable: true
          description: 'Alert condition type. Determines how the value is evaluated: absolute_value, relative_increase, or relative_decrease.'
        state:
          type: string
          readOnly: true
          description: 'Current alert state: Firing, Not firing, Errored, or Snoozed.'
        enabled:
          type: boolean
          description: Whether the alert is actively being evaluated.
        last_notified_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        last_checked_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        next_check_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        checks:
          type: array
          items:
            $ref: '#/components/schemas/AlertCheck'
          readOnly: true
          description: Alert check results. By default returns the last 5. Use checks_date_from and checks_date_to (e.g. '-24h', '-7d') to get checks within a time window, checks_limit to cap how many are returned (default 5, max 500), and checks_offset to skip the newest N checks for pagination (0-based). Newest checks first. Only populated on retrieve.
        checks_total:
          type: integer
          nullable: true
          readOnly: true
          description: Total alert checks matching the retrieve filters (date window). Only set on alert retrieve; omitted otherwise.
        config:
          allOf:
          - $ref: '#/components/schemas/TrendsAlertConfig'
          nullable: true
          description: Trends-specific alert configuration. Includes series_index (which series to monitor) and check_ongoing_interval (whether to check the current incomplete interval).
        detector_config:
          allOf:
          - $ref: '#/components/schemas/DetectorConfig'
          nullable: true
        calculation_interval:
          allOf:
          - $ref: '#/components/schemas/CalculationIntervalEnum'
          description: 'How often the alert is checked: hourly, daily, weekly, or monthly.


            * `hourly` - hourly

            * `daily` - daily

            * `weekly` - weekly

            * `monthly` - monthly'
        snoozed_until:
          type: string
          nullable: true
          description: Snooze the alert until this time. Pass a relative date string (e.g. '2h', '1d') or null to unsnooze.
        skip_weekend:
          type: boolean
          nullable: true
          description: Skip alert evaluation on weekends (Saturday and Sunday, local to project timezone).
        schedule_restriction:
          allOf:
          - $ref: '#/components/schemas/AlertScheduleRestriction'
          nullable: true
          description: 'Blocked local time windows (HH:MM in the project timezone). Interval is half-open [start, end): start inclusive, end exclusive. Use blocked_windows array of {start, end}. Null disables.'
        last_value:
          type: number
          format: double
          readOnly: true
          nullable: true
          description: The last calculated value from the most recent alert check.
        investigation_agent_enabled:
          type: boolean
          description: When enabled, an investigation agent runs on the state transition to firing and writes findings to a Notebook linked from the alert check. Only effective for detector-based (anomaly) alerts.
        investigation_gates_notifications:
          type: boolean
          description: When enabled (and investigation_agent_enabled is on), notification dispatch is held until the investigation agent produces a verdict. Notifications are suppressed when the verdict is false_positive (and optionally when inconclusive). A safety-net task force-fires after a few minutes if the investigation stalls.
        investigation_inconclusive_action:
          allOf:
          - $ref: '#/components/schemas/InvestigationInconclusiveActionEnum'
          description: 'How to handle an ''inconclusive'' verdict when notifications are gated. ''notify'' is the safe default — an agent that can''t be sure is itself useful signal.


            * `notify` - Notify

            * `suppress` - Suppress'
      required:
      - checks
      - checks_total
      - created_at
      - created_by
      - id
      - insight
      - last_checked_at
      - last_notified_at
      - last_value
      - next_check_at
      - state
      - subscribed_users
      - threshold
    LOFDetectorConfig:
      additionalProperties: false
      properties:
        n_neighbors:
          default: null
          description: 'Number of neighbors for LOF (default: 20)'
          title: N Neighbors
          type: integer
          nullable: true
        preprocessing:
          default: null
          description: Preprocessing transforms applied before detection
          allOf:
          - $ref: '#/components/schemas/PreprocessingConfig'
          nullable: true
        threshold:
          default: null
          description: 'Anomaly probability threshold (default: 0.9)'
          title: Threshold
          type: number
          nullable: true
        type:
          default: lof
          title: Type
          type: string
          enum:
          - lof
        window:
          default: null
          description: 'Rolling window size — how many historical data points to train on (default: based on calculation interval)'
          title: Window
          type: integer
          nullable: true
      title: LOFDetectorConfig
      type: object
    PaginatedAlertList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=400&limit=100
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=200&limit=100
        results:
          type: array
          items:
            $ref: '#/components/schemas/Alert'
    COPODDetectorConfig:
      additionalProperties: false
      properties:
        preprocessing:
          default: null
          description: Preprocessing transforms applied before detection
          allOf:
          - $ref: '#/components/schemas/PreprocessingConfig'
          nullable: true
        threshold:
          default: null
          description: 'Anomaly probability threshold (default: 0.9)'
          title: Threshold
          type: number
          nullable: true
        type:
          default: copod
          title: Type
          type: string
          enum:
          - copod
        window:
          default: null
          description: 'Rolling window size — how many historical data points to train on (default: based on calculation interval)'
          title: Window
          type: integer
          nullable: true
      title: COPODDetectorConfig
      type: object
    ECODDetectorConfig:
      additionalProperties: false
      properties:
        preprocessing:
          default: null
          description: Preprocessing transforms applied before detection
          allOf:
          - $ref: '#/components/schemas/PreprocessingConfig'
          nullable: true
        threshold:
          default: null
          description: 'Anomaly probability threshold (default: 0.9)'
          title: Threshold
          type: number
          nullable: true
        type:
          default: ecod
          title: Type
          type: string
          enum:
          - ecod
        window:
          default: null
          description: 'Rolling window size — how many historical data points to train on (default: based on calculation interval)'
          title: Window
          type: integer
          nullable: true
      title: ECODDetectorConfig
      type: object
    AlertCheck:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        calculated_value:
          type: number
          format: double
          readOnly: true
          nullable: true
        state:
          allOf:
          - $ref: '#/components/schemas/AlertCheckStateEnum'
          readOnly: true
        targets_notified:
          type: boolean
          readOnly: true
        anomaly_scores:
          readOnly: true
          nullable: true
        triggered_points:
          readOnly: true
          nullable: true
        triggered_dates:
          readOnly: true
          nullable: true
        interval:
          type: string
          readOnly: true
          nullable: true
        triggered_metadata:
          readOnly: true
          nullable: true
        investigation_status:
          readOnly: true
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/InvestigationStatusEnum'
          - $ref: '#/components/schemas/NullEnum'
        investigation_verdict:
          readOnly: true
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/InvestigationVerdictEnum'
          - $ref: '#/components/schemas/NullEnum'
        investigation_summary:
          type: string
          readOnly: true
          nullable: true
        investigation_notebook_short_id:
          type: string
          nullable: true
          readOnly: true
          description: Short ID of the Notebook produced by the investigation agent, when the agent ran for this check.
        notification_sent_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        notification_suppressed_by_agent:
          type: boolean
          readOnly: true
      required:
      - anomaly_scores
      - calculated_value
      - created_at
      - id
      - interval
      - investigation_notebook_short_id
      - investigation_status
      - investigation_summary
      - investigation_verdict
      - notification_sent_at
      - notification_suppressed_by_agent
      - state
      - targets_notified
      - triggered_dates
      - triggered_metadata
      - triggered_points
    InsightThresholdType:
      enum:
      - absolute
      - percentage
      title: InsightThresholdType
      type: string
    NullEnum:
      enum:
      - null
    PatchedAlert:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        created_by:
          allOf:
          - $ref: '#/components/schemas/UserBasic'
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        insight:
          type: integer
          description: 'Insight ID monitored by this alert. Note: Response returns full InsightBasicSerializer object.'
        name:
          type: string
          description: Human-readable name for the alert.
        subscribed_users:
          type: array
          items:
            type: integer
          description: 'User IDs to subscribe to this alert. Note: Response returns full UserBasicSerializer object.'
        threshold:
          allOf:
          - $ref: '#/components/schemas/Threshold'
          description: Threshold configuration with bounds and type for evaluating the alert.
        condition:
          allOf:
          - $ref: '#/components/schemas/AlertCondition'
          nullable: true
          description: 'Alert condition type. Determines how the value is evaluated: absolute_value, relative_increase, or relative_decrease.'
        state:
          type: string
          readOnly: true
          description: 'Current alert state: Firing, Not firing, Errored, or Snoozed.'
        enabled:
          type: boolean
          description: Whether the alert is actively being evaluated.
        last_notified_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        last_checked_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        next_check_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        checks:
          type: array
          items:
            $ref: '#/components/schemas/AlertCheck'
          readOnly: true
          description: Alert check results. By default returns the last 5. Use checks_date_from and checks_date_to (e.g. '-24h', '-7d') to get checks within a time window, checks_limit to cap how many are returned (default 5, max 500), and checks_offset to skip the newest N checks for pagination (0-based). Newest checks first. Only populated on retrieve.
        checks_total:
          type: integer
          nullable: true
          readOnly: true
          description: Total alert checks matching the retrieve filters (date window). Only set on alert retrieve; omitted otherwise.
        config:
          allOf:
          - $ref: '#/components/schemas/TrendsAlertConfig'
          nullable: true
          description: Trends-specific alert configuration. Includes series_index (which series to monitor) and check_ongoing_interval (whether to check the current incomplete interval).
        detector_config:
          allOf:
          - $ref: '#/components/schemas/DetectorConfig'
          nullable: true
        calculation_interval:
          allOf:
          - $ref: '#/components/schemas/CalculationIntervalEnum'
          description: 'How often the alert is checked: hourly, daily, weekly, or monthly.


            * `hourly` - hourly

            * `daily` - daily

            * `weekly` - weekly

            * `monthly` - monthly'
        snoozed_until:
          type: string
          nullable: true
          description: Snooze the alert until this time. Pass a relative date string (e.g. '2h', '1d') or null to unsnooze.
        skip_weekend:
          type: boolean
          nullable: true
          description: Skip alert evaluation on weekends (Saturday and Sunday, local to project timezone).
        schedule_restriction:
          allOf:
          - $ref: '#/components/schemas/AlertScheduleRestriction'
          nullable: true
          description: 'Blocked local time windows (HH:MM in the project timezone). Interval is half-open [start, end): start inclusive, end exclusive. Use blocked_windows array of {start, end}. Null disables.'
        last_value:
          type: number
          format: double
          readOnly: true
          nullable: true
          description: The last calculated value from the most recent alert check.
        investigation_agent_enabled:
          type: boolean
          description: When enabled, an investigation agent runs on the state transition to firing and writes findings to a Notebook linked from the alert check. Only effective for detector-based (anomaly) alerts.
        investigation_gates_notifications:
          type: boolean
          description: When enabled (and investigation_agent_enabled is on), notification dispatch is held until the investigation agent produces a verdict. Notifications are suppressed when the verdict is false_positive (and optionally when inconclusive). A safety-net task force-fires after a few minutes if the investigation stalls.
        investigation_inconclusive_action:
          allOf:
          - $ref: '#/components/schemas/InvestigationInconclusiveActionEnum'
          description: 'How to handle an ''inconclusive'' verdict when notifications are gated. ''notify'' is the safe default — an agent that can''t be sure is itself useful signal.


            * `notify` - Notify

            * `suppress` - Suppress'
    ThresholdDetectorConfig:
      additionalProperties: false
      properties:
        lower_bound:
          default: null
          description: Lower bound - values below this are anomalies
          title: Lower Bound
          type: number
          nullable: true
        preprocessing:
          default: null
          description: Preprocessing transforms applied before detection
          allOf:
          - $ref: '#/components/schemas/PreprocessingConfig'
          nullable: true
        type:
          default: threshold
          title: Type
          type: string
          enum:
          - threshold
        upper_bound:
          default: null
          description: Upper bound - values above this are anomalies
          title: Upper Bound
          type: number
          nullable: true
      title: ThresholdDetectorConfig
      type: object
    MADDetectorConfig:
      additionalProperties: false
      properties:
        preprocessing:
          default: null
          description: Preprocessing transforms applied before detection
          allOf:
          - $ref: '#/components/schemas/PreprocessingConfig'
          nullable: true
        threshold:
          default: null
          description: 'Anomaly probability threshold [0-1]. Points above this probability are flagged (default: 0.9)'
          title: Threshold
          type: number
          nullable: true
        type:
          default: mad
          title: Type
          type: string
          enum:
          - mad
        window:
          default: null
          description: 'Rolling window size for calculating median/MAD (default: 30)'
          title: Window
          type: integer
          nullable: true
      title: MADDetectorConfig
      type: object
    UserBasic:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        uuid:
          type: string
          format: uuid
          readOnly: true
        distinct_id:
          type: string
          nullable: true
          maxLength: 200
        first_name:
          type: string
          maxLength: 150
        last_name:
          type: string
          maxLength: 150
        email:
          type: string
          format: email
          title: Email address
          maxLength: 254
        is_email_verified:
          type: boolean
          nullable: true
        hedgehog_config:
          type: object
          additionalProperties: true
          nullable: true
          readOnly: true
        role_at_organization:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/RoleAtOrganizationEnum'
          - $ref: '#/components/schemas/BlankEnum'
          - $ref: '#/components/schemas/NullEnum'
      required:
      - email
      - hedgehog_config
      - id
      - uuid
    InsightThreshold:
      additionalProperties: false
      properties:
        bounds:
          default: null
          allOf:
          - $ref: '#/components/schemas/InsightsThresholdBounds'
          nullable: true
        type:
          description: Whether bounds are compared as absolute values or as percentage change from the previous interval.
          allOf:
          - $ref: '#/components/schemas/InsightThresholdType'
      required:
      - type
      title: InsightThreshold
      type: object
    TrendsAlertConfig:
      additionalProperties: false
      properties:
        check_ongoing_interval:
          default: null
          description: When true, evaluate the current (still incomplete) time interval in addition to completed ones.
          title: Check Ongoing Interval
          type: boolean
          nullable: true
        series_index:
          description: Zero-based index of the series in the insight's query to monitor.
          title: Series Index
          type: integer
        type:
          default: TrendsAlertConfig
          title: Type
          type: string
          enum:
          - TrendsAlertConfig
      required:
      - series_index
      title: TrendsAlertConfig
      type: object
    DetectorConfig:
      anyOf:
      - $ref: '#/components/schemas/EnsembleDetectorConfig'
      - $ref: '#/components/schemas/ZScoreDetectorConfig'
      - $ref: '#/components/schemas/MADDetectorConfig'
      - $ref: '#/components/schemas/IQRDetectorConfig'
      - $ref: '#/components/schemas/ThresholdDetectorConfig'
      - $ref: '#/components/schemas/ECODDetectorConfig'
      - $ref: '#/components/schemas/COPODDetectorConfig'
      - $ref: '#/components/schemas/IsolationForestDetectorConfig'
      - $ref: '#/components/schemas/KNNDetectorConfig'
      - $ref: '#/components/schemas/HBOSDetectorConfig'
      - $ref: '#/components/schemas/LOFDetectorConfig'
      - $ref: '#/components/schemas/OCSVMDetectorConfig'
      - $ref: '#/components/schemas/PCADetectorConfig'
      description: Detector configuration types
      title: DetectorConfig
    InvestigationVerdictEnum:
      enum:
      - true_positive
      - false_positive
      - inconclusive
      type: string
      description: '* `true_positive` - true_positive

        * `false_positive` - false_positive

        * `inconclusive` - inconclusive'
    AlertSimulateResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: number
            format: double
          description: Data values for each point.
        dates:
          type: array
          items:
            type: string
          description: Date labels for each point.
        scores:
          type: array
          items:
            type: number
            format: double
            nullable: true
          description: Anomaly score for each point (null if insufficient data).
        triggered_indices:
          type: array
          items:
            type: integer
          description: Indices of points flagged as anomalies.
        triggered_dates:
          type: array
          items:
            type: string
          description: Dates of points flagged as anomalies.
        interval:
          type: string
          nullable: true
          description: Interval of the trends query (hour, day, week, month).
        total_points:
          type: integer
          description: Total number of data points analyzed.
        anomaly_count:
          type: integer
          description: Number of anomalies detected.
        sub_detector_scores:
          type: array
          items:
            type: object
            additionalProperties: true
          description: Per-sub-detector scores for ensemble detectors. Each entry has 'type' and 'scores' fields.
        breakdown_results:
          type: array
          items:
            $ref: '#/components/schemas/BreakdownSimulationResult'
          description: Per-breakdown-value simulation results. Present only when the insight has breakdowns (up to 25 values).
      required:
      - anomaly_count
      - data
      - dates
      - interval
      - scores
      - total_points
      - triggered_dates
      - triggered_indices
    PCADetectorConfig:
      additionalProperties: false
      properties:
        preprocessing:
          default: null
          description: Preprocessing transforms applied before detection
          allOf:
          - $ref: '#/components/schemas/PreprocessingConfig'
          nullable: true
        threshold:
          default: null
          description: 'Anomaly probability threshold (default: 0.9)'
          title: Threshold
          type: number
          nullable: true
        type:
          default: pca
          title: Type
          type: string
          enum:
          - pca
        window:
          default: null
          description: 'Rolling window size — how many historical data points to train on (default: based on calculation interval)'
          title: Window
          type: integer
          nullable: true
      title: PCADetectorConfig
      type: object
    Method:
      enum:
      - largest
      - mean
      - median
      title: Method
      type: string
    OCSVMDetectorConfig:
      additionalProperties: false
      properties:
        kernel:
          default: null
          description: 'SVM kernel type (default: "rbf")'
          title: Kernel
          type: string
          nullable: true
        nu:
          default: null
          description: 'Upper bound on training errors fraction (default: 0.1)'
          title: Nu
          type: number
          nullable: true
        preprocessing:
          default: null
          description: Preprocessing transforms applied before detection
          allOf:
          - $ref: '#/components/schemas/PreprocessingConfig'
          nullable: true
        threshold:
          default: null
          description: 'Anomaly probability threshold (default: 0.9)'
          title: Threshold
          type: number
          nullable: true
        type:
          default: ocsvm
          title: Type
          type: string
          enum:
          - ocsvm
        window:
          default: null
          description: 'Rolling window size — how many historical data points to train on (default: based on calculation interval)'
          title: Window
          type: integer
          nullable: true
      title: OCSVMDetectorConfig
      type: object
    AlertScheduleRestrictionWindow:
      additionalProperties: false
      properties:
        start:
          description: Start time HH:MM (24-hour, project timezone). Inclusive. Each window must span ≥ 30 minutes on the local daily timeline (half-open [start, end)).
          title: Start
          type: string
        end:
          description: End time HH:MM (24-hour). Exclusive (half-open interval). Each window must span ≥ 30 minutes locally.
          title: End
          type: string
      required:
      - start
      - end
      title: AlertScheduleRestrictionWindow
      type: object
    AlertConditionType:
      enum:
      - absolute_value
      - relative_increase
      - relative_decrease
      title: AlertConditionType
      type: string
    PreprocessingConfig:
      additionalProperties: false
      properties:
        diffs_n:
          default: null
          description: 'Order of differencing. 0 = raw values, 1 = first-order diffs (default: 0)'
          title: Diffs N
          type: integer
          nullable: true
        lags_n:
          default: null
          description: 'Number of lag features. 0 = none, >0 = include n lagged values (default: 0)'
          title: Lags N
          type: integer
          nullable: true
        smooth_n:
          default: null
          description: 'Moving average window size. 0 = no smoothing, >1 = smooth over n points (default: 0)'
          title: Smooth N
          type: integer
          nullable: true
      title: PreprocessingConfig
      type: object
    EnsembleDetectorConfig:
      additionalProperties: false
      properties:
        detectors:
          description: Sub-detector configurations (minimum 2)
          items:
            anyOf:
            - $ref: '#/components/schemas/ZScoreDetectorConfig'
            - $ref: '#/components/schemas/MADDetectorConfig'
            - $ref: '#/components/schemas/IQRDetectorConfig'
            - $ref: '#/components/schemas/ThresholdDetectorConfig'
            - $ref: '#/components/schemas/ECODDetectorConfig'
            - $ref: '#/components/schemas/COPODDetectorConfig'
            - $ref: '#/components/schemas/IsolationForestDetectorConfig'
            - $ref: '#/components/schemas/KNNDetectorConfig'
            - $ref: '#/components/schemas/HBOSDetectorConfig'
            - $ref: '#/components/schemas/LOFDetectorConfig'
            - $ref: '#/components/schemas/OCSVMDetectorConfig'
            - $ref: '#/components/schemas/PCADetectorConfig'
          title: Detectors
          type: array
        operator:
          description: How to combine sub-detector results
          allOf:
          - $ref: '#/components/schemas/EnsembleOperator'
        type:
          default: ensemble
          title: Type
          type: string
          enum:
          - ensemble
      required:
      - detectors
      - operator
      title: EnsembleDetectorConfig
      type: object
    HBOSDetectorConfig:
      additionalProperties: false
      properties:
        n_bins:
          default: null
          description: 'Number of histogram bins (default: 10)'
          title: N Bins
          type: integer
          nullable: true
        preprocessing:
          default: null
          description: Preprocessing transforms applied before detection
          allOf:
          - $ref: '#/components/schemas/PreprocessingConfig'
          nullable: true
        threshold:
          default: null
          description: 'Anomaly probability threshold (default: 0.9)'
          title: Threshold
          type: number
          nullable: true
        type:
          default: hbos
          title: Type
          type: string
          enum:
          - hbos
        window:
          default: null
          description: 'Rolling window size — how many historical data points to train on (default: based on calculation interval)'
          title: Window
          type: integer
          nullable: true
      title: HBOSDetectorConfig
      type: object
    IsolationForestDetectorConfig:
      additionalProperties: false
      properties:
        n_estimators:
          default: null
          description: 'Number of trees in the forest (default: 100)'
          title: N Estimators
          type: integer
          nullable: true
        preprocessing:
          default: null
          description: Preprocessing transforms applied before detection
          allOf:
          - $ref: '#/components/schemas/PreprocessingConfig'
          nullable: true
        threshold:
          default: null
          description: 'Anomaly probability threshold (default: 0.9)'
          title: Threshold
          type: number
          nullable: true
        type:
          default: isolation_forest
          title: Type
          type: string
          enum:
          - isolation_forest
        window:
          default: null
          description: 'Rolling window size — how many historical data points to train on (default: based on calculation interval)'
          title: Window
          type: integer
          nullable: true
      title: IsolationForestDetectorConfig
      type: object
    BreakdownSimulationResult:
      type: object
      properties:
        label:
          type: string
          description: Breakdown value label.
        data:
          type: array
          items:
            type: number
            format: double
          description: Data values for each point.
        dates:
          type: array
          items:
            type: string
          description: Date labels for each point.
        scores:
          type: array
          items:
            type: number
            format: double
            nullable: true
          description: Anomaly score for each point.
        triggered_indices:
          type: array
          items:
            type: integer
          description: Indices of points flagged as anomalies.
        triggered_dates:
          type: array
          items:
            type: string
          description: Dates of points flagged as anomalies.
        total_points:
          type: integer
          description: Total number of data points analyzed.
        anomaly_count:
          type: integer
          description: Number of anomalies detected.
        sub_detector_scores:
          type: array
          items:
            type: object
            additionalProperties: true
          description: Per-sub-detector scores for ensemble detectors.
      required:
      - anomaly_count
      - data
      - dates
      - label
      - scores
      - total_points
      - triggered_dates
      - triggered_indices
    BlankEnum:
      enum:
      - ''
    Threshold:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        name:
          type: string
          description: Optional name for the threshold.
        configuration:
          allOf:
          - $ref: '#/components/schemas/InsightThreshold'
          description: Threshold bounds and type. Includes bounds (lower/upper floats) and type (absolute or percentage).
      required:
      - configuration
      - created_at
      - id
    AlertSimulate:
      type: object
      properties:
        insight:
          type: integer
          description: Insight ID to simulate the detector on.
        detector_config:
          allOf:
          - $ref: '#/components/schemas/DetectorConfig'
          description: Detector configuration to simulate.
        series_index:
          type: integer
          default: 0
          description: Zero-based index of the series to analyze.
        date_from:
          type: string
          nullable: true
          description: Relative date string for how far back to simulate (e.g. '-24h', '-30d', '-4w'). If not provided, uses the detector's minimum required samples.
      required:
      - detector_config
      - insight
    ZScoreDetectorConfig:
      additionalProperties: false
      properties:
        preprocessing:
          default: null
          description: Preprocessing transforms applied before detection
          allOf:
          - $ref: '#/components/schemas/PreprocessingConfig'
          nullable: true
        threshold:
          default: null
          description: 'Anomaly probability threshold [0-1]. Points above this probability are flagged (default: 0.9)'
          title: Threshold
          type: number
          nullable: true
        type:
          default: zscore
          title: Type
          type: string
          enum:
          - zscore
        window:
          default: null
          description: 'Rolling window size for calculating mean/std (default: 30)'
          title: Window
          type: integer
          nullable: true
      title: ZScoreDetectorConfig
      type: object
    AlertScheduleRestriction:
      additionalProperties: false
      properties:
        blocked_windows:
          description: Blocked local time windows when the alert must not run. Overlapping or identical windows are merged when saved. At most five windows before normalization; empty array clears quiet hours.
          items:
            $ref: '#/components/schemas/AlertScheduleRestrictionWindow'
          title: Blocked Windows
          type: array
      required:
      - blocked_windows
      title: AlertScheduleRestriction
      type: object
    KNNDetectorConfig:
      additionalProperties: false
      properties:
        method:
          default: null
          description: 'Distance method: ''largest'', ''mean'', ''median'' (default: ''largest'')'
          allOf:
          - $ref: '#/components/schemas/Method'
          nullable: true
        n_neighbors:
          default: null
          description: 'Number of neighbors to consider (default: 5)'
          title: N Neighbors
          type: integer
          nullable: true
        preprocessing:
          default: null
          description: Preprocessing transforms applied before detection
          allOf:
          - $ref: '#/components/schemas/PreprocessingConfig'
          nullable: true
        threshold:
          default: null
          description: 'Anomaly probability threshold (default: 0.9)'
          title: Threshold
          type: number
          nullable: true
        type:
          default: knn
          title: Type
          type: string
          enum:
          - knn
        window:
          default: null
          description: 'Rolling window size — how many historical data points to train on (default: based on calculation interval)'
          title: Window
          type: integer
          nullable: true
      title: KNNDetectorConfig
      type: object
  parameters:
    EnvironmentIdPath:
      in: path
      name: environment_id
      required: true
      schema:
        type: string
      description: Deprecated. Use /api/projects/{project_id}/ instead.
    ProjectIdPath:
      in: path
      name: project_id
      required: true
      schema:
        type: string
      description: Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.
  securitySchemes:
    PersonalAPIKeyAuth:
      type: http
      scheme: bearer
x-tagGroups:
- name: All endpoints
  tags:
  - LLM Analytics
  - actions
  - activity_log
  - activity_logs
  - advanced_activity_logs
  - alerts
  - annotations
  - approval_policies
  - batch_exports
  - cdp
  - change_requests
  - code
  - code-invites
  - cohorts
  - comments
  - conversations
  - core
  - customer_analytics
  - customer_journeys
  - customer_profile_configs
  - dashboard_templates
  - dashboards
  - data_color_themes
  - data_modeling_jobs
  - data_warehouse
  - dataset_items
  - datasets
  - desktop_recordings
  - domains
  - early_access_feature
  - early_access_features
  - elements
  - endpoints
  - environments
  - error_tracking
  - evaluation_runs
  - evaluations
  - event_definitions
  - event_filter
  - event_schemas
  - events
  - experiment_holdouts
  - experiment_saved_metrics
  - experiments
  - exports
  - external_data_schemas
  - external_data_sources
  - feature_flags
  - file_system
  - file_system_shortcut
  - flag_value
  - groups
  - groups_types
  - health_issues
  - heatmap_screenshots
  - heatmaps
  - hog_flows
  - hog_function_templates
  - hog_functions
  - insight_variables
  - insights
  - integrations
  - invites
  - js-snippet
  - legal_documents
  - lineage
  - live_debugger_breakpoints
  - llm_analytics
  - llm_prompts
  - llm_skills
  - logs
  - managed_viewsets
  - max
  - max_tools
  - mcp_server_installations
  - mcp_servers
  - mcp_store
  - mcp_tools
  - members
  - notebooks
  - oauth_applications
  - object_media_previews
  - organizations
  - persisted_folder
  - persons
  - platform_features
  - plugin_configs
  - product_analytics
  - product_tours
  - project_secret_api_keys
  - projects
  - property_definitions
  - proxy_records
  - public_hog_function_templates
  - query
  - replay
  - reverse_proxy
  - role_external_references
  - roles
  - sandbox-environments
  - sandbox_environments
  - saved
  - schema_property_groups
  - sdk_doctor
  - session_group_summaries
  - session_recording_playlists
  - session_recordings
  - session_summaries
  - sessions
  - signals
  - subscriptions
  - surveys
  - taggers
  - task-automations
  - task-runs
  - task_automations
  - tasks
  - uploaded_media
  - user_home_settings
  - user_interviews
  - users
  - visual_review
  - warehouse_dag
  - warehouse_model_paths
  - warehouse_saved_queries
  - warehouse_saved_query_folders
  - warehouse_tables
  - warehouse_view_link
  - warehouse_view_links
  - web_analytics
  - web_experiments
  - web_vitals
  - welcome
  - workflows