openapi: 3.0.2
info:
  title: Algolia Monitoring API
  description: >-
    The Algolia Monitoring API is a tool that allows users to track and analyze
    the performance of their Algolia search implementations in real-time. This
    API provides key performance indicators such as response times, search
    latency, indexing rates, and user behavior metrics. By monitoring these
    metrics, users can identify potential issues, optimize their search
    performance, and enhance the overall user experience on their applications.
    The Algolia Monitoring API gives users valuable insights into how their
    search functionality is performing and helps them make informed decisions to
    improve their search capabilities.
  version: 1.0.0
servers:
  - url: https://status.algolia.com
tags:
  - name: Monitoring
paths:
  /{path}:
    get:
      operationId: customGet
      summary: Send requests to the Algolia REST API
      description: This method allow you to send requests to the Algolia REST API.
      parameters:
        - $ref: '#/components/parameters/PathInPath'
        - $ref: '#/components/parameters/Parameters'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
      tags:
        - Monitoring
    post:
      operationId: customPost
      requestBody:
        description: Parameters to send with the custom request.
        content:
          application/json:
            schema:
              type: object
      summary: Send requests to the Algolia REST API
      description: This method allow you to send requests to the Algolia REST API.
      parameters:
        - $ref: '#/components/parameters/PathInPath'
        - $ref: '#/components/parameters/Parameters'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
      tags:
        - Monitoring
    put:
      operationId: customPut
      requestBody:
        description: Parameters to send with the custom request.
        content:
          application/json:
            schema:
              type: object
      summary: Send requests to the Algolia REST API
      description: This method allow you to send requests to the Algolia REST API.
      parameters:
        - $ref: '#/components/parameters/PathInPath'
        - $ref: '#/components/parameters/Parameters'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
      tags:
        - Monitoring
    delete:
      operationId: customDelete
      summary: Send requests to the Algolia REST API
      description: This method allow you to send requests to the Algolia REST API.
      parameters:
        - $ref: '#/components/parameters/PathInPath'
        - $ref: '#/components/parameters/Parameters'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
      tags:
        - Monitoring
  /1/status:
    get:
      operationId: getStatus
      summary: Algolia Retrieve status of all clusters
      security: []
      tags:
        - Monitoring
      description: Retrieves the status of all Algolia clusters and instances.
      responses:
        '200':
          $ref: '#/components/responses/StatusResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
  /1/status/{clusters}:
    get:
      summary: Algolia Retrieve cluster status
      description: Retrieves the status of selected clusters.
      operationId: getClusterStatus
      tags:
        - Monitoring
      security: []
      parameters:
        - $ref: '#/components/parameters/Clusters'
      responses:
        '200':
          $ref: '#/components/responses/StatusResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
  /1/incidents:
    get:
      summary: Algolia Retrieve all incidents
      description: Retrieves known incidents for all clusters.
      operationId: getIncidents
      security: []
      tags:
        - Monitoring
      responses:
        '200':
          $ref: '#/components/responses/IncidentsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
  /1/incidents/{clusters}:
    get:
      summary: Algolia Retrieve cluster incidents
      description: Retrieves known incidents for the selected clusters.
      operationId: getClusterIncidents
      tags:
        - Monitoring
      security: []
      parameters:
        - $ref: '#/components/parameters/Clusters'
      responses:
        '200':
          $ref: '#/components/responses/IncidentsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
  /1/inventory/servers:
    get:
      summary: Algolia Retrieve servers
      operationId: getServers
      security:
        - appId: []
        - apiKey: []
      description: |
        Retrieves the servers that belong to clusters.

        The response depends on whether you authenticate your API request:

        - With authentication, the response lists the servers assigned to your
        Algolia application's cluster.

        - Without authentication, the response lists the servers for all Algolia
        clusters.
      tags:
        - Monitoring
      responses:
        '200':
          $ref: '#/components/responses/InventoryResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
  /1/latency/{clusters}:
    get:
      summary: Algolia Retrieve search latency times
      description: Retrieves the average latency for search requests for selected clusters.
      operationId: getLatency
      security: []
      tags:
        - Monitoring
      parameters:
        - $ref: '#/components/parameters/Clusters'
      responses:
        '200':
          $ref: '#/components/responses/LatencyResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
  /1/indexing/{clusters}:
    get:
      summary: Algolia Retrieve indexing times
      description: Retrieves average times for indexing operations for selected clusters.
      operationId: getIndexingTime
      security: []
      tags:
        - Monitoring
      parameters:
        - $ref: '#/components/parameters/Clusters'
      responses:
        '200':
          $ref: '#/components/responses/IndexingResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
  /1/reachability/{clusters}/probes:
    get:
      summary: Algolia Test the reachability of clusters
      description: Test whether clusters are reachable or not.
      operationId: getReachability
      security: []
      tags:
        - Monitoring
      parameters:
        - $ref: '#/components/parameters/Clusters'
      responses:
        '200':
          $ref: '#/components/responses/ReachabilityResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
  /1/infrastructure/{metric}/period/{period}:
    get:
      summary: Algolia Retrieve metrics
      description: >
        Retrieves metrics related to your Algolia infrastructure, aggregated
        over a selected time window.


        Access to this API is available as part of the [Premium or Elevate
        plans](https://www.algolia.com/pricing).

        You must authenticate requests with the `x-algolia-application-id` and
        `x-algolia-api-key` headers (using the Monitoring API key).
      operationId: getMetrics
      tags:
        - Monitoring
      parameters:
        - $ref: '#/components/parameters/MetricInPath'
        - $ref: '#/components/parameters/PeriodInPath'
      responses:
        '200':
          $ref: '#/components/responses/InfrastructureResponse'
        '401':
          $ref: '#/components/responses/InfrastructureAPIUnauthorized'
  /setClientApiKey:
    get:
      x-helper: true
      x-asynchronous-helper: false
      tags:
        - Monitoring
      operationId: setClientApiKey
      summary: Algolia Switch the API key used to authenticate requests
      description: |
        Switch the API key used to authenticate requests.
      parameters:
        - in: query
          name: apiKey
          description: API key to be used from now on.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No content.
components:
  securitySchemes:
    appId:
      type: apiKey
      in: header
      name: X-Algolia-Application-Id
      description: Your Algolia application ID.
    apiKey:
      type: apiKey
      in: header
      name: X-Algolia-API-Key
      description: Your Algolia Monitoring API key.
  parameters:
    PathInPath:
      name: path
      in: path
      description: Path of the endpoint, anything after "/1" must be specified.
      required: true
      schema:
        type: string
        example: /keys
    Parameters:
      name: parameters
      in: query
      description: Query parameters to apply to the current query.
      schema:
        type: object
        additionalProperties: true
    Clusters:
      name: clusters
      in: path
      required: true
      description: Subset of clusters, separated by commas.
      schema:
        type: string
        example: c1-de,c2-de,c3-de
    MetricInPath:
      name: metric
      in: path
      required: true
      description: >
        Metric to report.


        For more information about the individual metrics, see the description
        of the API response.

        To include all metrics, use `*`.
      schema:
        $ref: '#/components/schemas/Metric'
    PeriodInPath:
      name: period
      in: path
      required: true
      description: |
        Period over which to aggregate the metrics:

        - `minute`. Aggregate the last minute. 1 data point per 10 seconds.
        - `hour`. Aggregate the last hour. 1 data point per minute.
        - `day`. Aggregate the last day. 1 data point per 10 minutes.
        - `week`. Aggregate the last week. 1 data point per hour.
        - `month`. Aggregate the last month. 1 data point per day.
      schema:
        $ref: '#/components/schemas/Period'
  schemas:
    ErrorBase:
      description: Error.
      type: object
      x-keep-model: true
      additionalProperties: true
      properties:
        message:
          type: string
          example: Invalid Application-Id or API-Key
    Status:
      title: status
      type: string
      description: Status of the cluster.
      enum:
        - operational
        - degraded_performance
        - partial_outage
        - major_outage
    Timestamp:
      type: integer
      format: int64
      description: Timestamp, measured in milliseconds since the Unix epoch.
    Incident:
      title: incident
      description: Incident details.
      type: object
      properties:
        title:
          type: string
          description: Description of the incident.
        status:
          $ref: '#/components/schemas/Status'
    Incidents:
      title: incidents
      description: >-
        Key-value pairs with the cluster names as keys and the list of incidents
        reported for this cluster as values.
      type: array
      items:
        title: incidentEntry
        type: object
        properties:
          t:
            $ref: '#/components/schemas/Timestamp'
          v:
            $ref: '#/components/schemas/Incident'
    Region:
      title: region
      type: string
      description: Region where the cluster is located.
      enum:
        - au
        - br
        - ca
        - de
        - eu
        - hk
        - in
        - jp
        - sg
        - uae
        - uk
        - usc
        - use
        - usw
        - za
      example: de
    ServerStatus:
      title: status
      type: string
      enum:
        - PRODUCTION
    Type:
      title: type
      type: string
      enum:
        - cluster
    Server:
      title: server
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          description: Server name.
          example: c16-de-1
        region:
          $ref: '#/components/schemas/Region'
        is_slave:
          type: boolean
          default: false
          deprecated: true
          description: |
            Included to support legacy applications.
            Use `is_replica` instead.
          example: false
        is_replica:
          type: boolean
          default: false
          description: Whether this server is a replica of another server.
          example: false
        cluster:
          type: string
          description: Name of the cluster to which this server belongs.
          example: c16-de
        status:
          $ref: '#/components/schemas/ServerStatus'
        type:
          $ref: '#/components/schemas/Type'
    Time:
      title: times
      description: Time measured by a probe.
      type: array
      items:
        title: timeEntry
        type: object
        additionalProperties: false
        properties:
          t:
            $ref: '#/components/schemas/Timestamp'
          v:
            type: integer
            description: Time in ms.
    Probes:
      title: probes
      description: Probes and their response.
      type: object
      additionalProperties:
        x-additionalPropertiesName: probe
        type: boolean
        description: >-
          Key-value pair with the probe name as the key and the reachability
          status as the value.
    Metric:
      type: string
      enum:
        - avg_build_time
        - ssd_usage
        - ram_search_usage
        - ram_indexing_usage
        - cpu_usage
        - '*'
      example: '*'
    Period:
      type: string
      enum:
        - minute
        - hour
        - day
        - week
        - month
      example: week
    ProbesMetric:
      title: metric
      type: object
      additionalProperties: false
      properties:
        t:
          $ref: '#/components/schemas/Timestamp'
        v:
          type: integer
          description: Value of the metric.
    InfraProbes:
      title: probes
      type: array
      items:
        $ref: '#/components/schemas/ProbesMetric'
  responses:
    BadRequest:
      description: Bad request or request arguments.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    FeatureNotEnabled:
      description: This feature is not enabled on your Algolia account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    MethodNotAllowed:
      description: Method not allowed with this API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    IndexNotFound:
      description: Index not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    StatusResponse:
      description: OK
      content:
        application/json:
          schema:
            title: statusResponse
            type: object
            properties:
              status:
                type: object
                additionalProperties:
                  x-additionalPropertiesName: cluster
                  $ref: '#/components/schemas/Status'
          examples:
            Success:
              value:
                status:
                  c16-de: operational
    UnauthorizedResponse:
      description: Unauthorized
      content:
        text/plain:
          schema:
            type: string
          examples:
            Unauthorized:
              summary: Invalid credentials
              description: Use the Monitoring API key.
              value: Invalid credentials
    NotFoundResponse:
      description: Not Found.
      content:
        text/plain:
          schema:
            type: string
          examples:
            NotFound:
              value: Unknown cluster "test"
    IncidentsResponse:
      description: OK
      content:
        application/json:
          schema:
            title: incidentsResponse
            type: object
            properties:
              incidents:
                type: object
                additionalProperties:
                  x-additionalPropertiesName: cluster
                  $ref: '#/components/schemas/Incidents'
          examples:
            success:
              value:
                incidents:
                  m134-de:
                    - t: 1687441685000
                      v:
                        title: >
                          Incident on cluster m134-de: Everything operating
                          normally.
                        status: operational
                    - t: 1687441579000
                      v:
                        title: >
                          Incident on cluster m134-de: We are encountering a
                          major

                          issue that impact all API calls.
                        status: major_outage
    InventoryResponse:
      description: OK
      content:
        application/json:
          schema:
            title: inventoryResponse
            type: object
            properties:
              inventory:
                type: array
                items:
                  $ref: '#/components/schemas/Server'
          examples:
            Success:
              value:
                inventory:
                  - name: c16-de-3
                    region: de
                    is_slave: false
                    is_replica: false
                    cluster: c16-de
                    status: PRODUCTION
                    type: cluster
                  - name: c16-de-2
                    region: de
                    is_slave: false
                    is_replica: false
                    cluster: c16-de
                    status: PRODUCTION
                    type: cluster
                  - name: c16-de-1
                    region: de
                    is_slave: false
                    is_replica: false
                    cluster: c16-de
                    status: PRODUCTION
                    type: cluster
    ForbiddenResponse:
      description: Forbidden
      content:
        application/json:
          schema:
            title: forbidden
            type: object
            additionalProperties: false
            properties:
              reason:
                type: string
          examples:
            Forbidden:
              value:
                reason: invalid credentials
    LatencyResponse:
      description: OK
      content:
        application/json:
          schema:
            title: latencyResponse
            type: object
            properties:
              metrics:
                title: latencyMetric
                type: object
                additionalProperties: false
                properties:
                  latency:
                    additionalProperties:
                      x-additionalPropertiesName: latencies
                      $ref: '#/components/schemas/Time'
          examples:
            Success:
              value:
                metrics:
                  latency:
                    c16-de:
                      - t: 1688056200000
                        v: 64
                      - t: 1688056800000
                        v: 59
                      - t: 1688057400000
                        v: 55
    BadRequestResponse:
      description: Bad Request.
      content:
        application/json:
          schema:
            title: badRequest
            type: object
            additionalProperties: false
            properties:
              reason:
                type: string
          examples:
            BadRequest:
              value:
                reason: Unknown servers
    IndexingResponse:
      description: OK
      content:
        application/json:
          schema:
            title: indexingTimeResponse
            type: object
            properties:
              metrics:
                title: indexingMetric
                type: object
                additionalProperties: false
                properties:
                  indexing:
                    additionalProperties:
                      x-additionalPropertiesName: cluster
                      $ref: '#/components/schemas/Time'
          examples:
            Success:
              value:
                metrics:
                  indexing:
                    c16-de:
                      - t: 1688056200000
                        v: 1562
                      - t: 1688056800000
                        v: 1637
                      - t: 1688057400000
                        v: 1754
    ReachabilityResponse:
      description: OK
      content:
        application/json:
          schema:
            title: reachabilityResponse
            type: object
            additionalProperties:
              x-additionalPropertiesName: cluster
              $ref: '#/components/schemas/Probes'
          examples:
            Success:
              value:
                c16-de:
                  sdn-probe-frankfurt: false
                  monitoring-2: false
                  sdn-probe-awswest1: false
    InfrastructureResponse:
      description: OK
      content:
        application/json:
          schema:
            title: infrastructureResponse
            type: object
            additionalProperties: false
            properties:
              metrics:
                title: metrics
                type: object
                additionalProperties: false
                properties:
                  cpu_usage:
                    type: object
                    description: CPU idleness in %.
                    additionalProperties:
                      x-additionalPropertiesName: probes
                      $ref: '#/components/schemas/InfraProbes'
                  ram_indexing_usage:
                    type: object
                    description: RAM used for indexing in MB.
                    additionalProperties:
                      x-additionalPropertiesName: probes
                      $ref: '#/components/schemas/InfraProbes'
                  ram_search_usage:
                    type: object
                    description: RAM used for search in MB.
                    additionalProperties:
                      x-additionalPropertiesName: probes
                      $ref: '#/components/schemas/InfraProbes'
                  ssd_usage:
                    type: object
                    description: >
                      Solid-state disk (SSD) usage expressed as % of RAM. 

                      0% means no SSD usage. A value of 50% indicates 32 GB
                      SSD usage for a machine with 64 RAM.
                    additionalProperties:
                      x-additionalPropertiesName: probes
                      $ref: '#/components/schemas/InfraProbes'
                  avg_build_time:
                    type: object
                    description: Average build time of the indices in seconds.
                    additionalProperties:
                      x-additionalPropertiesName: probes
                      $ref: '#/components/schemas/InfraProbes'
          examples:
            success:
              value:
                metrics:
                  cpu_usage:
                    s4-fr:
                      - t: 1455101280
                        v: 46
                      - t: 1455101290
                        v: 46
                      - t: 1455101300
                        v: 46
                    c3-use-1:
                      - t: 1455101280
                        v: 42
                      - t: 1455101290
                        v: 42
                      - t: 1455101300
                        v: 42
                      - t: 1455101310
                        v: 37
                    c3-use-2:
                      - t: 1455101280
                        v: 56
                      - t: 1455101290
                        v: 56
                      - t: 1455101300
                        v: 56
                      - t: 1455101310
                        v: 56
                      - t: 1455101320
                        v: 51
    InfrastructureAPIUnauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            title: unauthorized
            type: object
            additionalProperties: false
            properties:
              reason:
                type: string
          examples:
            Unauthorized:
              value:
                reason: >-
                  The infrastructure usage API is only available on Enterprise
                  plans. Please contact enterprise@algolia.com for more detail.
x-tagGroups:
  - name: General
    tags:
      - status
      - incidents
      - infrastructure
      - monitoring-tag