Skip to main content

​
Get Server Metrics

Retrieve system metrics including CPU, memory, disk, and network usage for server monitoring.
​
url
string
required
The URL endpoint for fetching metrics data
​
token
string
required
Bearer token for authentication
​
dataPoints
string
required
Number of data points to retrieve (limits the result set)

​
Authentication

This endpoint requires authentication using a Bearer token in the Authorization header: 
Authorization: Bearer YOUR_TOKEN

​
Response

Returns an array of metric objects containing system performance data:
​
cpu
string
Current CPU usage percentage
​
cpuModel
string
CPU model name
​
cpuCores
number
Number of CPU cores
​
cpuPhysicalCores
number
Number of physical CPU cores
​
cpuSpeed
number
CPU speed in GHz
​
os
string
Operating system name
​
distro
string
Linux distribution name
​
kernel
string
Kernel version
​
arch
string
System architecture (e.g., x64, arm64)
​
memUsed
string
Memory usage percentage
​
memUsedGB
string
Memory used in GB
​
memTotal
string
Total memory available
​
uptime
number
System uptime in seconds
​
diskUsed
string
Disk space used
​
totalDisk
string
Total disk space
​
networkIn
string
Network incoming traffic
​
networkOut
string
Network outgoing traffic
​
timestamp
string
Timestamp of the metrics snapshot

​
Example Request

curl -X GET "https://your-dokploy-instance.com/api/metrics?limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

[
  {
    "cpu": "15.5",
    "cpuModel": "Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz",
    "cpuCores": 12,
    "cpuPhysicalCores": 6,
    "cpuSpeed": 2.6,
    "os": "linux",
    "distro": "Ubuntu 22.04.3 LTS",
    "kernel": "5.15.0-91-generic",
    "arch": "x64",
    "memUsed": "45.2",
    "memUsedGB": "7.2",
    "memTotal": "16 GB",
    "uptime": 864231,
    "diskUsed": "120 GB",
    "totalDisk": "500 GB",
    "networkIn": "1.2 GB",
    "networkOut": "850 MB",
    "timestamp": "2024-03-15T10:30:00.000Z"
  }
]

​
Error Handling

The endpoint may return the following errors:
  • No monitoring data available: Monitoring service is not set up or no data has been collected yet
  • Container not running: The monitoring container is not active
  • Service not included: The service is not included in the monitoring configuration

​
Get Container Metrics

Retrieve metrics for specific Docker containers by application name.
​
url
string
required
The base URL endpoint for fetching container metrics
​
token
string
required
Bearer token for authentication
​
appName
string
required
Name of the application/container to monitor
​
dataPoints
string
required
Number of data points to retrieve

​
Authentication

Requires Bearer token authentication.

​
Response

Returns an array of container metric objects:
​
containerId
string
Unique container identifier
​
containerName
string
Name of the container
​
containerImage
string
Docker image used for the container
​
containerLabels
string
Labels associated with the container
​
containerCommand
string
Command running in the container
​
containerCreated
string
Container creation timestamp

​
Example Request

curl -X GET "https://your-dokploy-instance.com/api/metrics/containers?appName=my-app&limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

[
  {
    "containerId": "abc123def456",
    "containerName": "my-app-web-1",
    "containerImage": "nginx:latest",
    "containerLabels": "app=my-app,env=production",
    "containerCommand": "nginx -g 'daemon off;'",
    "containerCreated": "2024-03-15T08:00:00.000Z"
  }
]

​
Setup Monitoring

Configure monitoring settings for servers with metrics collection and thresholds.
This endpoint is available for admin users only and is disabled on Dokploy Cloud instances.

​
POST /admin.setupMonitoring

​
metricsConfig
object
required
Monitoring configuration settings
​
metricsConfig.server
object
required
Server-level monitoring configuration
​
refreshRate
number
required
Metrics refresh rate in seconds (minimum: 2)
​
port
number
required
Port for the monitoring service (minimum: 1)
​
token
string
required
Authentication token for the monitoring service
​
urlCallback
string
required
Callback URL for metrics delivery (must be valid URI)
​
retentionDays
number
required
Number of days to retain metrics data (minimum: 1)
​
cronJob
string
required
Cron expression for scheduled metrics collection
​
thresholds
object
required
Alert thresholds for resource usage
​
cpu
number
required
CPU usage threshold percentage (minimum: 0)
​
memory
number
required
Memory usage threshold percentage (minimum: 0)
​
metricsConfig.containers
object
required
Container-level monitoring configuration
​
refreshRate
number
required
Container metrics refresh rate in seconds (minimum: 2)
​
services
object
required
Service filtering configuration
​
include
array
Array of service names to include in monitoring
​
exclude
array
Array of service names to exclude from monitoring

​
Example Request

curl -X POST "https://your-dokploy-instance.com/api/admin.setupMonitoring" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -d '{
    "metricsConfig": {
      "server": {
        "refreshRate": 5,
        "port": 9090,
        "token": "secure-token-here",
        "urlCallback": "https://metrics.example.com/callback",
        "retentionDays": 30,
        "cronJob": "0 */5 * * * *",
        "thresholds": {
          "cpu": 80,
          "memory": 85
        }
      },
      "containers": {
        "refreshRate": 10,
        "services": {
          "include": ["web", "api", "worker"],
          "exclude": ["temp-container"]
        }
      }
    }
  }'

​
Example Response

{
  "success": true,
  "message": "Monitoring configured successfully"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us