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 metrics 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: metrics
paths:
  /api/v2/metrics:
    get:
      deprecated: false
      description: This endpoint returns a list of distinct metric names within the specified time range
      operationId: ListMetrics
      parameters:
      - in: query
        name: start
        schema:
          nullable: true
          type: integer
      - in: query
        name: end
        schema:
          nullable: true
          type: integer
      - in: query
        name: limit
        schema:
          type: integer
      - in: query
        name: searchText
        schema:
          type: string
      - in: query
        name: source
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/MetricsexplorertypesListMetricsResponse'
                  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 metric names
      tags:
      - metrics
  /api/v2/metrics/{metric_name}/alerts:
    get:
      deprecated: false
      description: This endpoint returns associated alerts for a specified metric
      operationId: GetMetricAlerts
      parameters:
      - in: path
        name: metric_name
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/MetricsexplorertypesMetricAlertsResponse'
                  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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderErrorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderErrorResponse'
          description: Internal Server Error
      security:
      - api_key:
        - VIEWER
      - tokenizer:
        - VIEWER
      summary: Get metric alerts
      tags:
      - metrics
  /api/v2/metrics/{metric_name}/attributes:
    get:
      deprecated: false
      description: This endpoint returns attribute keys and their unique values for a specified metric
      operationId: GetMetricAttributes
      parameters:
      - in: query
        name: start
        schema:
          nullable: true
          type: integer
      - in: query
        name: end
        schema:
          nullable: true
          type: integer
      - in: path
        name: metric_name
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/MetricsexplorertypesMetricAttributesResponse'
                  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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderErrorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderErrorResponse'
          description: Internal Server Error
      security:
      - api_key:
        - VIEWER
      - tokenizer:
        - VIEWER
      summary: Get metric attributes
      tags:
      - metrics
  /api/v2/metrics/{metric_name}/dashboards:
    get:
      deprecated: false
      description: This endpoint returns associated dashboards for a specified metric
      operationId: GetMetricDashboards
      parameters:
      - in: path
        name: metric_name
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/MetricsexplorertypesMetricDashboardsResponse'
                  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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderErrorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderErrorResponse'
          description: Internal Server Error
      security:
      - api_key:
        - VIEWER
      - tokenizer:
        - VIEWER
      summary: Get metric dashboards
      tags:
      - metrics
  /api/v2/metrics/{metric_name}/highlights:
    get:
      deprecated: false
      description: This endpoint returns highlights like number of datapoints, totaltimeseries, active time series, last received time for a specified metric
      operationId: GetMetricHighlights
      parameters:
      - in: path
        name: metric_name
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/MetricsexplorertypesMetricHighlightsResponse'
                  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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderErrorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderErrorResponse'
          description: Internal Server Error
      security:
      - api_key:
        - VIEWER
      - tokenizer:
        - VIEWER
      summary: Get metric highlights
      tags:
      - metrics
  /api/v2/metrics/{metric_name}/metadata:
    get:
      deprecated: false
      description: This endpoint returns metadata information like metric description, unit, type, temporality, monotonicity for a specified metric
      operationId: GetMetricMetadata
      parameters:
      - in: path
        name: metric_name
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/MetricsexplorertypesMetricMetadata'
                  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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderErrorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderErrorResponse'
          description: Internal Server Error
      security:
      - api_key:
        - VIEWER
      - tokenizer:
        - VIEWER
      summary: Get metric metadata
      tags:
      - metrics
    post:
      deprecated: false
      description: This endpoint helps to update metadata information like metric description, unit, type, temporality, monotonicity for a specified metric
      operationId: UpdateMetricMetadata
      parameters:
      - in: path
        name: metric_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetricsexplorertypesUpdateMetricMetadataRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: string
          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:
        - EDITOR
      - tokenizer:
        - EDITOR
      summary: Update metric metadata
      tags:
      - metrics
  /api/v2/metrics/inspect:
    post:
      deprecated: false
      description: Returns raw time series data points for a metric within a time range (max 30 minutes). Each series includes labels and timestamp/value pairs.
      operationId: InspectMetrics
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetricsexplorertypesInspectMetricsRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/MetricsexplorertypesInspectMetricsResponse'
                  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: Inspect raw metric data points
      tags:
      - metrics
  /api/v2/metrics/onboarding:
    get:
      deprecated: false
      description: Lightweight endpoint that checks if any non-SigNoz metrics have been ingested, used for onboarding status detection
      operationId: GetMetricsOnboardingStatus
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/MetricsexplorertypesMetricsOnboardingResponse'
                  status:
                    type: string
                required:
                - status
                - data
                type: object
          description: OK
        '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: Check if non-SigNoz metrics have been received
      tags:
      - metrics
  /api/v2/metrics/stats:
    post:
      deprecated: false
      description: This endpoint provides list of metrics with their number of samples and timeseries for the given time range
      operationId: GetMetricsStats
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetricsexplorertypesStatsRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/MetricsexplorertypesStatsResponse'
                  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: Get metrics statistics
      tags:
      - metrics
  /api/v2/metrics/treemap:
    post:
      deprecated: false
      description: This endpoint returns a treemap visualization showing the proportional distribution of metrics by sample count or time series count
      operationId: GetMetricsTreemap
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetricsexplorertypesTreemapRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/MetricsexplorertypesTreemapResponse'
                  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: Get metrics treemap
      tags:
      - metrics
components:
  schemas:
    MetricsexplorertypesTreemapResponse:
      properties:
        samples:
          items:
            $ref: '#/components/schemas/MetricsexplorertypesTreemapEntry'
          nullable: true
          type: array
        timeseries:
          items:
            $ref: '#/components/schemas/MetricsexplorertypesTreemapEntry'
          nullable: true
          type: array
      required:
      - timeseries
      - samples
      type: object
    MetricsexplorertypesListMetricsResponse:
      properties:
        metrics:
          items:
            $ref: '#/components/schemas/MetricsexplorertypesListMetric'
          nullable: true
          type: array
      required:
      - metrics
      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
    MetricsexplorertypesMetricDashboard:
      properties:
        dashboardId:
          type: string
        dashboardName:
          type: string
        widgetId:
          type: string
        widgetName:
          type: string
      required:
      - dashboardName
      - dashboardId
      - widgetId
      - widgetName
      type: object
    Querybuildertypesv5Label:
      properties:
        key:
          $ref: '#/components/schemas/TelemetrytypesTelemetryFieldKey'
        value: {}
      type: object
    TelemetrytypesSignal:
      enum:
      - traces
      - logs
      - metrics
      type: string
    MetricsexplorertypesMetricHighlightsResponse:
      properties:
        activeTimeSeries:
          minimum: 0
          type: integer
        dataPoints:
          minimum: 0
          type: integer
        lastReceived:
          minimum: 0
          type: integer
        totalTimeSeries:
          minimum: 0
          type: integer
      required:
      - dataPoints
      - lastReceived
      - totalTimeSeries
      - activeTimeSeries
      type: object
    MetricsexplorertypesMetricAttribute:
      properties:
        key:
          type: string
        valueCount:
          minimum: 0
          type: integer
        values:
          items:
            type: string
          nullable: true
          type: array
      required:
      - key
      - values
      - valueCount
      type: object
    MetricsexplorertypesListMetric:
      properties:
        description:
          type: string
        isMonotonic:
          type: boolean
        metricName:
          type: string
        temporality:
          $ref: '#/components/schemas/MetrictypesTemporality'
        type:
          $ref: '#/components/schemas/MetrictypesType'
        unit:
          type: string
      required:
      - metricName
      - description
      - type
      - unit
      - temporality
      - isMonotonic
      type: object
    MetrictypesType:
      enum:
      - gauge
      - sum
      - histogram
      - summary
      - exponentialhistogram
      type: string
    MetricsexplorertypesStatsResponse:
      properties:
        metrics:
          items:
            $ref: '#/components/schemas/MetricsexplorertypesStat'
          nullable: true
          type: array
        total:
          minimum: 0
          type: integer
      required:
      - metrics
      - total
      type: object
    MetricsexplorertypesMetricsOnboardingResponse:
      properties:
        hasMetrics:
          type: boolean
      required:
      - hasMetrics
      type: object
    Querybuildertypesv5Filter:
      properties:
        expression:
          type: string
      type: object
    MetricsexplorertypesStat:
      properties:
        description:
          type: string
        metricName:
          type: string
        samples:
          minimum: 0
          type: integer
        timeseries:
          minimum: 0
          type: integer
        type:
          $ref: '#/components/schemas/MetrictypesType'
        unit:
          type: string
      required:
      - metricName
      - description
      - type
      - unit
      - timeseries
      - samples
      type: object
    MetricsexplorertypesMetricAttributesResponse:
      properties:
        attributes:
          items:
            $ref: '#/components/schemas/MetricsexplorertypesMetricAttribute'
          nullable: true
          type: array
        totalKeys:
          format: int64
          type: integer
      required:
      - attributes
      - totalKeys
      type: object
    MetrictypesTemporality:
      enum:
      - delta
      - cumulative
      - unspecified
      type: string
    MetricsexplorertypesTreemapEntry:
      properties:
        metricName:
          type: string
        percentage:
          format: double
          type: number
        totalValue:
          minimum: 0
          type: integer
      required:
      - metricName
      - percentage
      - totalValue
      type: object
    MetricsexplorertypesInspectMetricsResponse:
      properties:
        series:
          items:
            $ref: '#/components/schemas/Querybuildertypesv5TimeSeries'
          nullable: true
          type: array
      required:
      - series
      type: object
    ErrorsResponseerroradditional:
      properties:
        message:
          type: string
      type: object
    MetricsexplorertypesStatsRequest:
      properties:
        end:
          format: int64
          type: integer
        filter:
          $ref: '#/components/schemas/Querybuildertypesv5Filter'
        limit:
          type: integer
        offset:
          type: integer
        orderBy:
          $ref: '#/components/schemas/Querybuildertypesv5OrderBy'
        start:
          format: int64
          type: integer
      required:
      - start
      - end
      - limit
      type: object
    MetricsexplorertypesUpdateMetricMetadataRequest:
      properties:
        description:
          type: string
        isMonotonic:
          type: boolean
        metricName:
          type: string
        temporality:
          $ref: '#/components/schemas/MetrictypesTemporality'
        type:
          $ref: '#/components/schemas/MetrictypesType'
        unit:
          type: string
      required:
      - metricName
      - type
      - description
      - unit
      - temporality
      - isMonotonic
      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
    MetricsexplorertypesTreemapMode:
      enum:
      - timeseries
      - samples
      type: string
    MetricsexplorertypesMetricDashboardsResponse:
      properties:
        dashboards:
          items:
            $ref: '#/components/schemas/MetricsexplorertypesMetricDashboard'
          nullable: true
          type: array
      required:
      - dashboards
      type: object
    TelemetrytypesTelemetryFieldKey:
      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
    ErrorsJSON:
      properties:
        code:
          type: string
        errors:
          items:
            $ref: '#/components/schemas/ErrorsResponseerroradditional'
          type: array
        message:
          type: string
        url:
          type: string
      required:
      - code
      - message
      type: object
    MetricsexplorertypesTreemapRequest:
      properties:
        end:
          format: int64
          type: integer
        filter:
          $ref: '#/components/schemas/Querybuildertypesv5Filter'
        limit:
          type: integer
        mode:
          $ref: '#/components/schemas/MetricsexplorertypesTreemapMode'
        start:
          format: int64
          type: integer
      required:
      - start
      - end
      - limit
      - mode
      type: object
    Querybuildertypesv5TimeSeriesValue:
      properties:
        bucket:
          $ref: '#/components/schemas/Querybuildertypesv5Bucket'
        partial:
          type: boolean
        timestamp:
          format: int64
          type: integer
        value:
          format: double
          type: number
        values:
          items:
            format: double
            type: number
          type: array
      type: object
    MetricsexplorertypesMetricMetadata:
      properties:
        description:
          type: string
        isMonotonic:
          type: boolean
        temporality:
          $ref: '#/components/schemas/MetrictypesTemporality'
        type:
          $ref: '#/components/schemas/MetrictypesType'
        unit:
          type: string
      required:
      - description
      - type
      - unit
      - temporality
      - isMonotonic
      type: object
    Querybuildertypesv5OrderDirection:
      enum:
      - asc
      - desc
      type: string
    TelemetrytypesFieldContext:
      enum:
      - metric
      - log
      - span
      - resource
      - attribute
      - body
      type: string
    Querybuildertypesv5Bucket:
      properties:
        step:
          format: double
          type: number
      type: object
    MetricsexplorertypesMetricAlert:
      properties:
        alertId:
          type: string
        alertName:
          type: string
      required:
      - alertName
      - alertId
      type: object
    MetricsexplorertypesInspectMetricsRequest:
      properties:
        end:
          format: int64
          type: integer
        filter:
          $ref: '#/components/schemas/Querybuildertypesv5Filter'
        metricName:
          type: string
        start:
          format: int64
          type: integer
      required:
      - metricName
      - start
      - end
      type: object
    Querybuildertypesv5TimeSeries:
      properties:
        labels:
          items:
            $ref: '#/components/schemas/Querybuildertypesv5Label'
          type: array
        values:
          items:
            $ref: '#/components/schemas/Querybuildertypesv5TimeSeriesValue'
          nullable: true
          type: array
      type: object
    MetricsexplorertypesMetricAlertsResponse:
      properties:
        alerts:
          items:
            $ref: '#/components/schemas/MetricsexplorertypesMetricAlert'
          nullable: true
          type: array
      required:
      - alerts
      type: object
  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