openapi: 3.0.3
info:
  contact:
    email: support@signoz.io
    name: SigNoz Support
    url: https://signoz.io
  description: OpenTelemetry-Native Logs, Metrics and Traces in a single pane
  termsOfService: https://signoz.io/terms-of-service/
  title: SigNoz alerts inframonitoring API
  version: ''
servers:
- description: The fully qualified URL to the SigNoz APIServer.
  url: https://{host}:{port}{base_path}
  variables:
    base_path:
      default: /
      description: The base path of the SigNoz APIServer
    host:
      default: localhost
      description: The host of the SigNoz APIServer
    port:
      default: '8080'
      description: The port of the SigNoz APIServer
tags:
- name: inframonitoring
paths:
  /api/v2/infra_monitoring/hosts:
    post:
      deprecated: false
      description: 'Returns a paginated list of hosts with key infrastructure metrics: CPU usage (%), memory usage (%), I/O wait (%), disk usage (%), and 15-minute load average. Each host includes its current status (active/inactive based on metrics reported in the last 10 minutes) and metadata attributes (e.g., os.type). Supports filtering via a filter expression, filtering by host status, custom groupBy to aggregate hosts by any attribute, ordering by any of the five metrics, and pagination via offset/limit. The response type is ''list'' for the default host.name grouping or ''grouped_list'' for custom groupBy keys. Also reports missing required metrics and whether the requested time range falls before the data retention boundary. Numeric metric fields (cpu, memory, wait, load15, diskUsage) return -1 as a sentinel when no data is available for that field.'
      operationId: ListHosts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InframonitoringtypesPostableHosts'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/InframonitoringtypesHosts'
                  status:
                    type: string
                required:
                - status
                - data
                type: object
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderErrorResponse'
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderErrorResponse'
          description: Internal Server Error
      security:
      - api_key:
        - VIEWER
      - tokenizer:
        - VIEWER
      summary: List Hosts for Infra Monitoring
      tags:
      - inframonitoring
  /api/v2/infra_monitoring/pods:
    post:
      deprecated: false
      description: 'Returns a paginated list of Kubernetes pods with key metrics: CPU usage, CPU request/limit utilization, memory working set, memory request/limit utilization, current pod phase (pending/running/succeeded/failed/unknown), and pod age (ms since start time). Each pod includes metadata attributes (namespace, node, workload owner such as deployment/statefulset/daemonset/job/cronjob, cluster). Supports filtering via a filter expression, custom groupBy to aggregate pods by any attribute, ordering by any of the six metrics (cpu, cpu_request, cpu_limit, memory, memory_request, memory_limit), and pagination via offset/limit. The response type is ''list'' for the default k8s.pod.uid grouping (each row is one pod with its current phase) or ''grouped_list'' for custom groupBy keys (each row aggregates pods in the group with per-phase counts: pendingPodCount, runningPodCount, succeededPodCount, failedPodCount, unknownPodCount derived from each pod''s latest phase in the window). Also reports missing required metrics and whether the requested time range falls before the data retention boundary. Numeric metric fields (podCPU, podCPURequest, podCPULimit, podMemory, podMemoryRequest, podMemoryLimit, podAge) return -1 as a sentinel when no data is available for that field.'
      operationId: ListPods
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InframonitoringtypesPostablePods'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/InframonitoringtypesPods'
                  status:
                    type: string
                required:
                - status
                - data
                type: object
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderErrorResponse'
          description: Forbidden
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderErrorResponse'
          description: Internal Server Error
      security:
      - api_key:
        - VIEWER
      - tokenizer:
        - VIEWER
      summary: List Pods for Infra Monitoring
      tags:
      - inframonitoring
components:
  schemas:
    InframonitoringtypesPodPhase:
      enum:
      - pending
      - running
      - succeeded
      - failed
      - unknown
      - ''
      type: string
    InframonitoringtypesHostFilter:
      properties:
        expression:
          type: string
        filterByStatus:
          $ref: '#/components/schemas/InframonitoringtypesHostStatus'
      type: object
    InframonitoringtypesPodRecord:
      properties:
        failedPodCount:
          type: integer
        meta:
          additionalProperties: {}
          nullable: true
          type: object
        pendingPodCount:
          type: integer
        podAge:
          format: int64
          type: integer
        podCPU:
          format: double
          type: number
        podCPULimit:
          format: double
          type: number
        podCPURequest:
          format: double
          type: number
        podMemory:
          format: double
          type: number
        podMemoryLimit:
          format: double
          type: number
        podMemoryRequest:
          format: double
          type: number
        podPhase:
          $ref: '#/components/schemas/InframonitoringtypesPodPhase'
        podUID:
          type: string
        runningPodCount:
          type: integer
        succeededPodCount:
          type: integer
        unknownPodCount:
          type: integer
      required:
      - podUID
      - podCPU
      - podCPURequest
      - podCPULimit
      - podMemory
      - podMemoryRequest
      - podMemoryLimit
      - podPhase
      - pendingPodCount
      - runningPodCount
      - succeededPodCount
      - failedPodCount
      - unknownPodCount
      - podAge
      - meta
      type: object
    Querybuildertypesv5OrderByKey:
      properties:
        description:
          type: string
        fieldContext:
          $ref: '#/components/schemas/TelemetrytypesFieldContext'
        fieldDataType:
          $ref: '#/components/schemas/TelemetrytypesFieldDataType'
        name:
          type: string
        signal:
          $ref: '#/components/schemas/TelemetrytypesSignal'
        unit:
          type: string
      required:
      - name
      type: object
    TelemetrytypesSignal:
      enum:
      - traces
      - logs
      - metrics
      type: string
    InframonitoringtypesRequiredMetricsCheck:
      properties:
        missingMetrics:
          items:
            type: string
          nullable: true
          type: array
      required:
      - missingMetrics
      type: object
    Querybuildertypesv5Filter:
      properties:
        expression:
          type: string
      type: object
    InframonitoringtypesResponseType:
      enum:
      - list
      - grouped_list
      type: string
    Querybuildertypesv5GroupByKey:
      properties:
        description:
          type: string
        fieldContext:
          $ref: '#/components/schemas/TelemetrytypesFieldContext'
        fieldDataType:
          $ref: '#/components/schemas/TelemetrytypesFieldDataType'
        name:
          type: string
        signal:
          $ref: '#/components/schemas/TelemetrytypesSignal'
        unit:
          type: string
      required:
      - name
      type: object
    InframonitoringtypesHostRecord:
      properties:
        activeHostCount:
          type: integer
        cpu:
          format: double
          type: number
        diskUsage:
          format: double
          type: number
        hostName:
          type: string
        inactiveHostCount:
          type: integer
        load15:
          format: double
          type: number
        memory:
          format: double
          type: number
        meta:
          additionalProperties: {}
          nullable: true
          type: object
        status:
          $ref: '#/components/schemas/InframonitoringtypesHostStatus'
        wait:
          format: double
          type: number
      required:
      - hostName
      - status
      - activeHostCount
      - inactiveHostCount
      - cpu
      - memory
      - wait
      - load15
      - diskUsage
      - meta
      type: object
    InframonitoringtypesPostableHosts:
      properties:
        end:
          format: int64
          type: integer
        filter:
          $ref: '#/components/schemas/InframonitoringtypesHostFilter'
        groupBy:
          items:
            $ref: '#/components/schemas/Querybuildertypesv5GroupByKey'
          nullable: true
          type: array
        limit:
          type: integer
        offset:
          type: integer
        orderBy:
          $ref: '#/components/schemas/Querybuildertypesv5OrderBy'
        start:
          format: int64
          type: integer
      required:
      - start
      - end
      - limit
      type: object
    InframonitoringtypesHosts:
      properties:
        endTimeBeforeRetention:
          type: boolean
        records:
          items:
            $ref: '#/components/schemas/InframonitoringtypesHostRecord'
          nullable: true
          type: array
        requiredMetricsCheck:
          $ref: '#/components/schemas/InframonitoringtypesRequiredMetricsCheck'
        total:
          type: integer
        type:
          $ref: '#/components/schemas/InframonitoringtypesResponseType'
        warning:
          $ref: '#/components/schemas/Querybuildertypesv5QueryWarnData'
      required:
      - type
      - records
      - total
      - requiredMetricsCheck
      - endTimeBeforeRetention
      type: object
    ErrorsResponseerroradditional:
      properties:
        message:
          type: string
      type: object
    Querybuildertypesv5QueryWarnData:
      properties:
        message:
          type: string
        url:
          type: string
        warnings:
          items:
            $ref: '#/components/schemas/Querybuildertypesv5QueryWarnDataAdditional'
          type: array
      type: object
    InframonitoringtypesPostablePods:
      properties:
        end:
          format: int64
          type: integer
        filter:
          $ref: '#/components/schemas/Querybuildertypesv5Filter'
        groupBy:
          items:
            $ref: '#/components/schemas/Querybuildertypesv5GroupByKey'
          nullable: true
          type: array
        limit:
          type: integer
        offset:
          type: integer
        orderBy:
          $ref: '#/components/schemas/Querybuildertypesv5OrderBy'
        start:
          format: int64
          type: integer
      required:
      - start
      - end
      - limit
      type: object
    TelemetrytypesFieldDataType:
      enum:
      - string
      - bool
      - float64
      - int64
      - number
      type: string
    Querybuildertypesv5OrderBy:
      properties:
        direction:
          $ref: '#/components/schemas/Querybuildertypesv5OrderDirection'
        key:
          $ref: '#/components/schemas/Querybuildertypesv5OrderByKey'
      type: object
    RenderErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorsJSON'
        status:
          type: string
      required:
      - status
      - error
      type: object
    InframonitoringtypesPods:
      properties:
        endTimeBeforeRetention:
          type: boolean
        records:
          items:
            $ref: '#/components/schemas/InframonitoringtypesPodRecord'
          nullable: true
          type: array
        requiredMetricsCheck:
          $ref: '#/components/schemas/InframonitoringtypesRequiredMetricsCheck'
        total:
          type: integer
        type:
          $ref: '#/components/schemas/InframonitoringtypesResponseType'
        warning:
          $ref: '#/components/schemas/Querybuildertypesv5QueryWarnData'
      required:
      - type
      - records
      - total
      - requiredMetricsCheck
      - endTimeBeforeRetention
      type: object
    ErrorsJSON:
      properties:
        code:
          type: string
        errors:
          items:
            $ref: '#/components/schemas/ErrorsResponseerroradditional'
          type: array
        message:
          type: string
        url:
          type: string
      required:
      - code
      - message
      type: object
    Querybuildertypesv5QueryWarnDataAdditional:
      properties:
        message:
          type: string
      type: object
    Querybuildertypesv5OrderDirection:
      enum:
      - asc
      - desc
      type: string
    TelemetrytypesFieldContext:
      enum:
      - metric
      - log
      - span
      - resource
      - attribute
      - body
      type: string
    InframonitoringtypesHostStatus:
      enum:
      - active
      - inactive
      - ''
      type: string
  securitySchemes:
    api_key:
      description: API Keys
      in: header
      name: SigNoz-Api-Key
      type: apiKey
    tokenizer:
      bearerFormat: Tokenizer
      description: Tokens generated by the tokenizer
      scheme: bearer
      type: http