Hostingsurge Metrics API

openapi: 3.2.0
info:
  title: Hostingsurge Platform Metrics API
  version: 1.0.0
  description: 'Deploy and operate projects on Hostingsurge: Git/upload/Docker/WordPress projects, deployments, logs, environment variables, domains and databases. Errors are {"error":{"code","message","details?"}}.'
servers:
- url: /api/v1
  description: Same origin as the dashboard, e.g. https://hostingsurge.com/api/v1
security:
- bearerAuth: []
- sessionCookie: []
tags:
- name: Metrics
paths:
  /projects/{projectId}/metrics:
    get:
      tags:
      - Metrics
      summary: 'CPU and memory of a project over time (per resource: the project, its previews…'
      parameters:
      - schema:
          type: string
          maxLength: 64
          format: uuid
        required: true
        name: projectId
        in: path
      - schema:
          type: string
          enum:
          - 1h
          - 24h
          - 7d
          - 30d
          default: 24h
        required: false
        name: range
        in: query
      responses:
        '200':
          description: Metrics
          content:
            application/json:
              schema:
                type: object
                properties:
                  projectId:
                    type: string
                    format: uuid
                  range:
                    type: string
                    enum:
                    - 1h
                    - 24h
                    - 7d
                    - 30d
                  resolutionSeconds:
                    type: integer
                  from:
                    type: string
                    description: ISO-8601 timestamp
                  to:
                    type: string
                    description: ISO-8601 timestamp
                  collecting:
                    type: boolean
                    description: 'the host collector reported within the last 5 minutes (false: graphs are not collected on this server yet)'
                  lastReportAt:
                    type:
                    - string
                    - 'null'
                    description: when the collector last reported (platform-wide)
                  oomKillsCounted:
                    type: boolean
                    description: 'false: the collector cannot read the kernel log, so oomKills stay 0'
                  plan:
                    type:
                    - object
                    - 'null'
                    properties:
                      cpus:
                        type: number
                      memoryMb:
                        type: integer
                    required:
                    - cpus
                    - memoryMb
                    description: the most CPU and memory one resource may get on the team's plan
                  series:
                    type: array
                    items:
                      type: object
                      properties:
                        kind:
                          type: string
                          enum:
                          - project
                          - preview
                          - database
                        id:
                          type: string
                          format: uuid
                          description: the project, preview or database id
                        name:
                          type: string
                          description: project name, preview branch or database name
                        allocation:
                          type:
                          - object
                          - 'null'
                          properties:
                            cpus:
                              type: number
                            memoryMb:
                              type: integer
                          required:
                          - cpus
                          - memoryMb
                          description: CPU and memory allocated to this resource; the graphs' limit line
                        containerLimits:
                          type:
                          - object
                          - 'null'
                          properties:
                            cpus:
                              type:
                              - number
                              - 'null'
                            memoryBytes:
                              type:
                              - number
                              - 'null'
                          required:
                          - cpus
                          - memoryBytes
                          description: 'limits the running containers actually have (null fields: none); new limits apply at the next start or restart'
                        latest:
                          type:
                          - object
                          - 'null'
                          properties:
                            at:
                              type: string
                              description: ISO-8601 timestamp
                            containers:
                              type: integer
                            cpuCores:
                              type:
                              - number
                              - 'null'
                            memoryBytes:
                              type:
                              - number
                              - 'null'
                          required:
                          - at
                          - containers
                          - cpuCores
                          - memoryBytes
                          description: 'the newest sample of the last 10 minutes (null: not running or not measured)'
                        summary:
                          type: object
                          properties:
                            cpuCoresAvg:
                              type:
                              - number
                              - 'null'
                            cpuCoresPeak:
                              type:
                              - number
                              - 'null'
                            memoryBytesAvg:
                              type:
                              - number
                              - 'null'
                            memoryBytesPeak:
                              type:
                              - number
                              - 'null'
                            restarts:
                              type: integer
                            oomKills:
                              type: integer
                            lastRestartAt:
                              type:
                              - string
                              - 'null'
                              description: start of the latest interval with a restart
                            lastOomKillAt:
                              type:
                              - string
                              - 'null'
                              description: ISO-8601 timestamp
                          required:
                          - cpuCoresAvg
                          - cpuCoresPeak
                          - memoryBytesAvg
                          - memoryBytesPeak
                          - restarts
                          - oomKills
                          - lastRestartAt
                          - lastOomKillAt
                        points:
                          type: array
                          items:
                            type: object
                            properties:
                              at:
                                type: string
                                description: start of the point's interval (resolutionSeconds long)
                              cpuCores:
                                type:
                                - number
                                - 'null'
                                description: average CPU use in cores (1 = one full CPU); null before a container's second sample
                              cpuCoresMax:
                                type:
                                - number
                                - 'null'
                                description: highest one-minute average within the interval
                              memoryBytes:
                                type:
                                - number
                                - 'null'
                                description: average memory in use (without reclaimable file cache)
                              memoryBytesMax:
                                type:
                                - number
                                - 'null'
                              restarts:
                                type: integer
                                description: times a container was restarted after it exited (a crash; a redeploy is not a restart)
                              oomKills:
                                type: integer
                                description: processes the kernel killed because the resource reached its memory limit
                            required:
                            - at
                            - cpuCores
                            - cpuCoresMax
                            - memoryBytes
                            - memoryBytesMax
                            - restarts
                            - oomKills
                      required:
                      - kind
                      - id
                      - name
                      - allocation
                      - containerLimits
                      - latest
                      - summary
                      - points
                    description: the project first, then its previews, then its databases
                required:
                - projectId
                - range
                - resolutionSeconds
                - from
                - to
                - collecting
                - lastReportAt
                - oomKillsCounted
                - plan
                - series
        '400':
          description: Invalid request (code invalid_request)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                        - unauthorized
                        - forbidden
                        - not_found
                        - invalid_request
                        - conflict
                        - limit_reached
                        - rate_limited
                        - provider_unavailable
                        - not_configured
                        - internal
                        - ip_not_allowed
                        - upgrade_required
                        - view_only
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties: {}
                    required:
                    - code
                    - message
                required:
                - error
        '401':
          description: Missing or invalid session/token (code unauthorized)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                        - unauthorized
                        - forbidden
                        - not_found
                        - invalid_request
                        - conflict
                        - limit_reached
                        - rate_limited
                        - provider_unavailable
                        - not_configured
                        - internal
                        - ip_not_allowed
                        - upgrade_required
                        - view_only
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties: {}
                    required:
                    - code
                    - message
                required:
                - error
        '403':
          description: Authenticated but not permitted (code forbidden; needs projects:read)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                        - unauthorized
                        - forbidden
                        - not_found
                        - invalid_request
                        - conflict
                        - limit_reached
                        - rate_limited
                        - provider_unavailable
                        - not_configured
                        - internal
                        - ip_not_allowed
                        - upgrade_required
                        - view_only
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties: {}
                    required:
                    - code
                    - message
                required:
                - error
        '404':
          description: Not found or not visible to the caller (code not_found)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                        - unauthorized
                        - forbidden
                        - not_found
                        - invalid_request
                        - conflict
                        - limit_reached
                        - rate_limited
                        - provider_unavailable
                        - not_configured
                        - internal
                        - ip_not_allowed
                        - upgrade_required
                        - view_only
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties: {}
                    required:
                    - code
                    - message
                required:
                - error
        '429':
          description: Too many requests (code rate_limited); see Retry-After
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                        - unauthorized
                        - forbidden
                        - not_found
                        - invalid_request
                        - conflict
                        - limit_reached
                        - rate_limited
                        - provider_unavailable
                        - not_configured
                        - internal
                        - ip_not_allowed
                        - upgrade_required
                        - view_only
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties: {}
                    required:
                    - code
                    - message
                required:
                - error
      operationId: getProjectsByProjectIdMetrics
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API or MCP key created in the dashboard (Account → API & MCP keys). Keys carry scopes and project grants.
    sessionCookie:
      type: apiKey
      in: cookie
      name: __Host-hs_session
      description: Dashboard session (same origin only; changes require a matching Origin header)