openapi: 3.0.2
info:
  title: Render Public Audit Logs Metrics API
  description: Manage everything about your Render services
  version: 1.0.0
  contact:
    name: Render API
    url: https://community.render.com
    email: support@render.com
servers:
- url: https://api.render.com/v1
security:
- BearerAuth: []
tags:
- name: Metrics
  description: The `Metrics` endpoints allow you to retrieve metrics for your services, Postgres databases, and redis instances.
paths:
  /metrics-stream/{ownerId}:
    parameters:
    - name: ownerId
      in: path
      required: true
      description: The ID of the workspace to return metrics stream information for
      schema:
        type: string
    get:
      summary: Retrieve metrics stream
      description: Returns metrics stream information for the specified workspace.
      operationId: getOwnerMetricsStream
      tags:
      - Metrics
      responses:
        '200':
          description: The metrics stream integration for the owner
          content:
            application/json:
              schema:
                $ref: '#/paths/~1metrics-stream~1%7BownerId%7D/put/responses/200/content/application~1json/schema'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '404':
          description: metrics stream not found
        '500':
          $ref: '#/components/responses/500InternalServerError'
    put:
      summary: Create or update metrics stream
      description: Creates or updates the metrics stream for the specified workspace.
      operationId: upsertOwnerMetricsStream
      tags:
      - Metrics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Input for creating or updating a metrics stream
              properties:
                provider:
                  type: string
                  description: Provider to send metrics to
                  enum:
                  - BETTER_STACK
                  - GRAFANA
                  - DATADOG
                  - NEW_RELIC
                  - HONEYCOMB
                  - SIGNOZ
                  - GROUNDCOVER
                  - CUSTOM
                url:
                  description: The endpoint URL to stream metrics to
                  type: string
                token:
                  description: Authentication token for the metrics stream
                  type: string
      responses:
        '200':
          description: metrics stream successfully updated
          content:
            application/json:
              schema:
                type: object
                required:
                - ownerId
                - provider
                - url
                properties:
                  ownerId:
                    description: The ID of the owner
                    type: string
                  provider:
                    $ref: '#/paths/~1metrics-stream~1%7BownerId%7D/put/requestBody/content/application~1json/schema/properties/provider'
                  url:
                    description: The endpoint URL to stream metrics to
                    type: string
        '400':
          $ref: '#/components/responses/400BadRequest'
        '500':
          $ref: '#/components/responses/500InternalServerError'
    delete:
      summary: Delete metrics stream
      description: Deletes the metrics stream for the specified workspace.
      operationId: deleteOwnerMetricsStream
      tags:
      - Metrics
      responses:
        '204':
          description: metrics stream integration deleted successfully
        '400':
          $ref: '#/components/responses/400BadRequest'
        '404':
          description: metrics stream not found
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /metrics/cpu:
    parameters:
    - $ref: '#/components/parameters/startTimeParam'
    - $ref: '#/components/parameters/endTimeParam'
    - name: resolutionSeconds
      in: query
      schema:
        type: number
        minimum: 30
        example: 60
        default: 60
      required: false
      description: The resolution of the returned data
    - name: resource
      in: query
      description: Resource ID to query. When multiple resource query params are provided, they are ORed together. Resources can be service ids, Postgres ids, or Redis ids
      schema:
        type: string
        example: srv-xxxxx,dpg-xxxxx,red-xxxxx
    - name: service
      in: query
      deprecated: true
      description: This parameter is deprecated. Please use `resource` instead
      schema:
        type: string
        example: srv-xxxxx
    - name: instance
      in: query
      required: false
      description: Instance ID to query. When multiple instance ID query params are provided, they are ORed together
      schema:
        type: string
        example: srv-xxxxx-yyyy
    - name: aggregationMethod
      in: query
      required: false
      description: The aggregation method to apply to multiple time series
      schema:
        type: string
        enum:
        - AVG
        - MAX
        - MIN
    get:
      summary: Get CPU usage
      description: 'Get CPU usage for one or more resources.

        '
      operationId: get-cpu
      tags:
      - Metrics
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: array
                description: A collection of time series
                required:
                - items
                items:
                  type: object
                  description: A time series data point
                  required:
                  - labels
                  - values
                  - unit
                  properties:
                    labels:
                      type: array
                      description: List of labels describing the time series
                      items:
                        type: object
                        description: A time series datapoint label
                        required:
                        - field
                        - value
                        properties:
                          field:
                            type: string
                            example: service
                          value:
                            type: string
                            example: srv-xxxxx
                    values:
                      type: array
                      description: The values of the time series
                      items:
                        description: A time series datapoint value
                        type: object
                        required:
                        - timestamp
                        - value
                        - unit
                        properties:
                          timestamp:
                            type: string
                            format: date-time
                            example: '2021-06-17T08:15:30Z'
                          value:
                            type: number
                            example: 1
                    unit:
                      type: string
                      example: GB
        '400':
          $ref: '#/components/responses/400BadRequest'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /metrics/cpu-limit:
    parameters:
    - $ref: '#/components/parameters/startTimeParam'
    - $ref: '#/components/parameters/endTimeParam'
    - $ref: '#/paths/~1metrics~1cpu/parameters/2'
    - $ref: '#/paths/~1metrics~1cpu/parameters/3'
    - $ref: '#/paths/~1metrics~1cpu/parameters/4'
    - $ref: '#/paths/~1metrics~1cpu/parameters/5'
    get:
      summary: Get CPU limit
      description: 'Get the CPU limit for one or more resources.

        '
      operationId: get-cpu-limit
      tags:
      - Metrics
      responses:
        '200':
          $ref: '#/paths/~1metrics~1cpu/get/responses/200'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /metrics/cpu-target:
    parameters:
    - $ref: '#/components/parameters/startTimeParam'
    - $ref: '#/components/parameters/endTimeParam'
    - $ref: '#/paths/~1metrics~1cpu/parameters/2'
    - $ref: '#/paths/~1metrics~1cpu/parameters/3'
    - $ref: '#/paths/~1metrics~1cpu/parameters/4'
    - $ref: '#/paths/~1metrics~1cpu/parameters/5'
    get:
      summary: Get CPU target
      description: 'Get CPU target for one or more resources.

        '
      operationId: get-cpu-target
      tags:
      - Metrics
      responses:
        '200':
          $ref: '#/paths/~1metrics~1cpu/get/responses/200'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /metrics/memory:
    parameters:
    - $ref: '#/components/parameters/startTimeParam'
    - $ref: '#/components/parameters/endTimeParam'
    - $ref: '#/paths/~1metrics~1cpu/parameters/2'
    - $ref: '#/paths/~1metrics~1cpu/parameters/3'
    - $ref: '#/paths/~1metrics~1cpu/parameters/4'
    - $ref: '#/paths/~1metrics~1cpu/parameters/5'
    get:
      summary: Get memory usage
      description: 'Get memory usage for one or more resources.

        '
      operationId: get-memory
      tags:
      - Metrics
      responses:
        '200':
          $ref: '#/paths/~1metrics~1cpu/get/responses/200'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /metrics/memory-limit:
    parameters:
    - $ref: '#/components/parameters/startTimeParam'
    - $ref: '#/components/parameters/endTimeParam'
    - $ref: '#/paths/~1metrics~1cpu/parameters/2'
    - $ref: '#/paths/~1metrics~1cpu/parameters/3'
    - $ref: '#/paths/~1metrics~1cpu/parameters/4'
    - $ref: '#/paths/~1metrics~1cpu/parameters/5'
    get:
      summary: Get memory limit
      description: 'Get the memory limit for one or more resources.

        '
      operationId: get-memory-limit
      tags:
      - Metrics
      responses:
        '200':
          $ref: '#/paths/~1metrics~1cpu/get/responses/200'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /metrics/memory-target:
    parameters:
    - $ref: '#/components/parameters/startTimeParam'
    - $ref: '#/components/parameters/endTimeParam'
    - $ref: '#/paths/~1metrics~1cpu/parameters/2'
    - $ref: '#/paths/~1metrics~1cpu/parameters/3'
    - $ref: '#/paths/~1metrics~1cpu/parameters/4'
    - $ref: '#/paths/~1metrics~1cpu/parameters/5'
    get:
      summary: Get memory target
      description: 'Get memory target for one or more resources.

        '
      operationId: get-memory-target
      tags:
      - Metrics
      responses:
        '200':
          $ref: '#/paths/~1metrics~1cpu/get/responses/200'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /metrics/http-requests:
    parameters:
    - $ref: '#/components/parameters/startTimeParam'
    - $ref: '#/components/parameters/endTimeParam'
    - $ref: '#/paths/~1metrics~1cpu/parameters/2'
    - $ref: '#/paths/~1metrics~1bandwidth/parameters/2'
    - $ref: '#/paths/~1metrics~1cpu/parameters/4'
    - $ref: '#/paths/~1metrics~1http-latency/parameters/5'
    - $ref: '#/paths/~1metrics~1http-latency/parameters/6'
    - name: aggregateBy
      in: query
      required: false
      description: The field to aggregate by
      schema:
        type: string
        enum:
        - statusCode
        - host
    get:
      summary: Get HTTP request count
      description: 'Get the HTTP request count for one or more resources.

        '
      operationId: get-http-requests
      tags:
      - Metrics
      responses:
        '200':
          $ref: '#/paths/~1metrics~1cpu/get/responses/200'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /metrics/http-latency:
    parameters:
    - $ref: '#/components/parameters/startTimeParam'
    - $ref: '#/components/parameters/endTimeParam'
    - $ref: '#/paths/~1metrics~1cpu/parameters/2'
    - $ref: '#/paths/~1metrics~1bandwidth/parameters/2'
    - $ref: '#/paths/~1metrics~1cpu/parameters/4'
    - name: host
      in: query
      required: false
      description: The hosts of HTTP requests to filter to. When multiple host query params are provided, they are ORed together
      schema:
        type: string
        example: example.com
    - name: path
      in: query
      required: false
      description: The paths of HTTP requests to filter to. When multiple path query params are provided, they are ORed together
      schema:
        type: string
        example: /graphql
    - name: quantile
      in: query
      required: false
      description: The quantile of latencies to fetch. When multiple quantile query params are provided, they are ORed together
      schema:
        type: number
        format: float
        example: 0.99
    get:
      summary: Get HTTP latency
      description: 'Get HTTP latency metrics for one or more resources.

        '
      operationId: get-http-latency
      tags:
      - Metrics
      responses:
        '200':
          $ref: '#/paths/~1metrics~1cpu/get/responses/200'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /metrics/bandwidth:
    parameters:
    - $ref: '#/components/parameters/startTimeParam'
    - $ref: '#/components/parameters/endTimeParam'
    - name: resource
      in: query
      description: Service ID to query. When multiple service ids are provided, they are ORed together
      schema:
        type: string
        example: srv-xxxxx
    - $ref: '#/paths/~1metrics~1cpu/parameters/4'
    get:
      summary: Get bandwidth usage
      description: 'Get bandwidth usage for one or more resources.

        '
      operationId: get-bandwidth
      tags:
      - Metrics
      responses:
        '200':
          $ref: '#/paths/~1metrics~1cpu/get/responses/200'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /metrics/bandwidth-sources:
    parameters:
    - $ref: '#/components/parameters/startTimeParam'
    - $ref: '#/components/parameters/endTimeParam'
    - $ref: '#/paths/~1metrics~1bandwidth/parameters/2'
    - $ref: '#/paths/~1metrics~1cpu/parameters/4'
    get:
      summary: Get bandwidth usage breakdown by traffic source
      description: 'Get bandwidth usage for one or more resources broken down by traffic source (HTTP, WebSocket, NAT, PrivateLink).


        Returns hourly data points with traffic source breakdown. Traffic source data is available from March 9, 2025 onwards.

        Queries for earlier dates will return a 400 Bad Request error.

        '
      operationId: get-bandwidth-sources
      tags:
      - Metrics
      responses:
        '200':
          description: A successful response with traffic source breakdown
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        labels:
                          type: object
                          properties:
                            resource:
                              type: string
                              example: srv-abc123
                            trafficSource:
                              type: string
                              enum:
                              - total
                              - http
                              - websocket
                              - nat
                              - privatelink
                              example: http
                        values:
                          type: array
                          items:
                            type: object
                            properties:
                              timestamp:
                                type: integer
                                example: 1709856000
                              value:
                                type: number
                                example: 100
              example:
                data:
                - labels:
                    resource: srv-abc123
                    trafficSource: total
                  values:
                  - timestamp: 1709856000
                    value: 125.5
                  - timestamp: 1709859600
                    value: 98.2
                - labels:
                    resource: srv-abc123
                    trafficSource: http
                  values:
                  - timestamp: 1709856000
                    value: 100
                  - timestamp: 1709859600
                    value: 75.8
                - labels:
                    resource: srv-abc123
                    trafficSource: websocket
                  values:
                  - timestamp: 1709856000
                    value: 25.5
                  - timestamp: 1709859600
                    value: 22.4
        '400':
          description: Bad request - invalid date range
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: bandwidth sources data is only available after 2025-03-09
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /metrics/disk-usage:
    parameters:
    - $ref: '#/components/parameters/startTimeParam'
    - $ref: '#/components/parameters/endTimeParam'
    - $ref: '#/paths/~1metrics~1cpu/parameters/2'
    - $ref: '#/paths/~1metrics~1cpu/parameters/3'
    - $ref: '#/paths/~1metrics~1cpu/parameters/4'
    get:
      summary: Get disk usage
      description: 'Get persistent disk usage for one or more resources.

        '
      operationId: get-disk-usage
      tags:
      - Metrics
      responses:
        '200':
          $ref: '#/paths/~1metrics~1cpu/get/responses/200'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /metrics/disk-capacity:
    parameters:
    - $ref: '#/components/parameters/startTimeParam'
    - $ref: '#/components/parameters/endTimeParam'
    - $ref: '#/paths/~1metrics~1cpu/parameters/2'
    - $ref: '#/paths/~1metrics~1cpu/parameters/3'
    - $ref: '#/paths/~1metrics~1cpu/parameters/4'
    get:
      summary: Get disk capacity
      description: 'Get persistent disk capacity for one or more resources.

        '
      operationId: get-disk-capacity
      tags:
      - Metrics
      responses:
        '200':
          $ref: '#/paths/~1metrics~1cpu/get/responses/200'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /metrics/instance-count:
    parameters:
    - $ref: '#/components/parameters/startTimeParam'
    - $ref: '#/components/parameters/endTimeParam'
    - $ref: '#/paths/~1metrics~1cpu/parameters/2'
    - $ref: '#/paths/~1metrics~1cpu/parameters/3'
    - $ref: '#/paths/~1metrics~1cpu/parameters/4'
    get:
      summary: Get instance count
      description: 'Get the instance count for one or more resources.

        '
      operationId: get-instance-count
      tags:
      - Metrics
      responses:
        '200':
          $ref: '#/paths/~1metrics~1cpu/get/responses/200'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /metrics/active-connections:
    parameters:
    - $ref: '#/components/parameters/startTimeParam'
    - $ref: '#/components/parameters/endTimeParam'
    - $ref: '#/paths/~1metrics~1cpu/parameters/2'
    - name: resource
      in: query
      description: Resource ID to query. When multiple resource query params are provided, they are ORed together. Resources Postgres ids or Redis ids
      schema:
        type: string
        example: dpg-xxxxx,red-xxxxx
    get:
      summary: Get active connection count
      description: 'Get the number of active connections for one or more Postgres databases or Redis instances.

        '
      operationId: get-active-connections
      tags:
      - Metrics
      responses:
        '200':
          $ref: '#/paths/~1metrics~1cpu/get/responses/200'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /metrics/replication-lag:
    parameters:
    - $ref: '#/components/parameters/startTimeParam'
    - $ref: '#/components/parameters/endTimeParam'
    - $ref: '#/paths/~1metrics~1cpu/parameters/2'
    - name: resource
      in: query
      description: Postgres ID to query. When multiple resource query params are provided, they are ORed together
      schema:
        type: string
        example: dpg-xxxxx
    get:
      summary: Get replica lag
      description: 'Get seconds of replica lag of a Postgres replica.

        '
      operationId: get-replication-lag
      tags:
      - Metrics
      responses:
        '200':
          $ref: '#/paths/~1metrics~1cpu/get/responses/200'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /metrics/filters/application:
    parameters:
    - $ref: '#/components/parameters/startTimeParam'
    - $ref: '#/components/parameters/endTimeParam'
    - $ref: '#/paths/~1metrics~1cpu/parameters/2'
    - $ref: '#/paths/~1metrics~1bandwidth/parameters/2'
    - $ref: '#/paths/~1metrics~1cpu/parameters/4'
    get:
      summary: List queryable instance values
      description: 'List instance values to filter by for one or more resources.

        '
      operationId: list-application-filter-values
      tags:
      - Metrics
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: array
                description: A collection of filter values for application metrics
                required:
                - items
                items:
                  type: object
                  properties:
                    filter:
                      type: string
                      enum:
                      - instance
                    values:
                      type: array
                      items:
                        type: string
                        example: srv-xxxxx-yyyy
        '400':
          $ref: '#/components/responses/400BadRequest'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /metrics/filters/http:
    parameters:
    - $ref: '#/components/parameters/startTimeParam'
    - $ref: '#/components/parameters/endTimeParam'
    - $ref: '#/paths/~1metrics~1cpu/parameters/2'
    - $ref: '#/paths/~1metrics~1bandwidth/parameters/2'
    - $ref: '#/paths/~1metrics~1cpu/parameters/4'
    - $ref: '#/paths/~1metrics~1http-latency/parameters/5'
    - name: statusCode
      in: query
      required: false
      description: The status codes of HTTP requests to filter to. When multiple status code query params are provided, they are ORed together
      schema:
        type: string
        example: '200'
    get:
      summary: List queryable status codes and host values
      description: 'List status codes and host values to filter by for one or more resources.

        '
      operationId: list-http-filter-values
      tags:
      - Metrics
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: array
                description: A collection of filter values for HTTP metrics
                required:
                - items
                items:
                  type: object
                  properties:
                    filter:
                      type: string
                      enum:
                      - host
                      - statusCode
                    values:
                      type: array
                      items:
                        type: string
                        example: api.example.com
        '400':
          $ref: '#/components/responses/400BadRequest'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /metrics/filters/path:
    parameters:
    - $ref: '#/components/parameters/startTimeParam'
    - $ref: '#/components/parameters/endTimeParam'
    - $ref: '#/paths/~1metrics~1cpu/parameters/2'
    - $ref: '#/paths/~1metrics~1bandwidth/parameters/2'
    - $ref: '#/paths/~1metrics~1cpu/parameters/4'
    - $ref: '#/paths/~1metrics~1http-latency/parameters/5'
    - $ref: '#/paths/~1metrics~1filters~1http/parameters/6'
    - $ref: '#/paths/~1metrics~1http-latency/parameters/6'
    get:
      summary: List queryable paths
      description: The path suggestions are based on the most recent 5000 log lines as filtered by the provided filters
      operationId: list-path-filter-values
      tags:
      - Metrics
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: array
                description: A collection of suggested paths to filter by
                required:
                - items
                items:
                  type: string
                  example: /user/*
        '400':
          $ref: '#/components/responses/400BadRequest'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /metrics/task-runs-queued:
    parameters:
    - $ref: '#/components/parameters/startTimeParam'
    - $ref: '#/components/parameters/endTimeParam'
    - $ref: '#/paths/~1metrics~1cpu/parameters/2'
    - name: resource
      in: query
      description: Task ID to query. When multiple task IDs are provided, they are ORed together
      schema:
        type: string
        example: tsk-xxxxx
    get:
      summary: Get task runs queued count
      description: 'Get the total number of task runs queued for one or more tasks.

        '
      operationId: get-task-runs-queued
      tags:
      - Metrics
      responses:
        '200':
          $ref: '#/paths/~1metrics~1cpu/get/responses/200'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '500':
          $ref: '#/components/responses/500InternalServerError'
  /metrics/task-runs-completed:
    parameters:
    - $ref: '#/components/parameters/startTimeParam'
    - $ref: '#/components/parameters/endTimeParam'
    - $ref: '#/paths/~1metrics~1cpu/parameters/2'
    - $ref: '#/paths/~1metrics~1task-runs-queued/parameters/3'
    - name: state
      in: query
      required: false
      description: The state of task runs to filter to. When multiple state query params are provided, they are ORed together
      schema:
        type: string
        enum:
        - succeeded
        - failed
    - name: aggregateBy
      in: query
      required: false
      description: The field to aggregate by
      schema:
        type: string
        enum:
        - state
    get:
      summary: Get task runs completed count
      description: 'Get the total number of task runs completed for one or more tasks. Optionally filter by state (succeeded/failed) or aggregate by state.

        '
      operationId: get-task-runs-completed
      tags:
      - Metrics
      responses:
        '200':
          $ref: '#/paths/~1metrics~1cpu/get/responses/200'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '500':
          $ref: '#/components/responses/500InternalServerError'
components:
  parameters:
    endTimeParam:
      name: endTime
      in: query
      schema:
        type: string
        format: date-time
        example: '2021-06-17T08:30:30Z'
      required: false
      description: Epoch/Unix timestamp of end of time range to return. Defaults to `now()`.
    startTimeParam:
      name: startTime
      in: query
      schema:
        type: string
        format: date-time
        example: '2021-06-17T08:15:30Z'
      required: false
      description: Epoch/Unix timestamp of start of time range to return. Defaults to `now() - 1 hour`.
  responses:
    500InternalServerError:
      description: An unexpected server error has occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
    400BadRequest:
      description: The request could not be understood by the server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
  schemas:
    error:
      type: object
      properties:
        id:
          type: string
        message:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
x-readme:
  metrics-enabled: false