unraid

Unraid API Skill

Query and monitor Unraid servers using the GraphQL API. Access all 27 read-only endpoints for system monitoring, disk health, logs, containers, VMs, and more.

Quick Start

Set your Unraid server credentials:

export UNRAID_URL="https://your-unraid-server/graphql"
export UNRAID_API_KEY="your-api-key"

Get API Key: Settings → Management Access → API Keys → Create (select "Viewer" role)

Use the helper script for any query:

./scripts/unraid-query.sh -q "{ online }"

Or run example scripts:

./scripts/dashboard.sh              # Complete multi-server dashboard
./examples/disk-health.sh           # Disk temperatures & health
./examples/read-logs.sh syslog 20   # Read system logs

Core Concepts

GraphQL API Structure

Unraid 7.2+ uses GraphQL (not REST). Key differences:

• Single endpoint: /graphql for all queries
• Request exactly what you need: Specify fields in query
• Strongly typed: Use introspection to discover fields
• No container logs: Docker container output logs not accessible

Two Resources for Stats

• info - Static hardware specs (CPU model, cores, OS version)
• metrics - Real-time usage (CPU %, memory %, current load)

Always use metrics for monitoring, info for specifications.

Common Tasks

System Monitoring

Check if server is online:

./scripts/unraid-query.sh -q "{ online }"

Get CPU and memory usage:

./scripts/unraid-query.sh -q "{ metrics { cpu { percentTotal } memory { used total percentTotal } } }"

Complete dashboard:

./scripts/dashboard.sh

Disk Management

Check disk health and temperatures:

./examples/disk-health.sh

Get array status:

./scripts/unraid-query.sh -q "{ array { state parityCheckStatus { status progress errors } } }"

List all physical disks (including cache/USB):

./scripts/unraid-query.sh -q "{ disks { name } }"

Storage Shares

List network shares:

./scripts/unraid-query.sh -q "{ shares { name comment } }"

Logs

List available logs:

./scripts/unraid-query.sh -q "{ logFiles { name size modifiedAt } }"

Read log content:

./examples/read-logs.sh syslog 20

Containers & VMs

List Docker containers:

./scripts/unraid-query.sh -q "{ docker { containers { names image state status } } }"

List VMs:

./scripts/unraid-query.sh -q "{ vms { name state cpus memory } } }"

Note: Container output logs are NOT accessible via API. Use docker logs via SSH.

Notifications

Get notification counts:

./scripts/unraid-query.sh -q "{ notifications { overview { unread { info warning alert total } } } }"

Helper Script Usage

The scripts/unraid-query.sh helper supports:

# Basic usage
./scripts/unraid-query.sh -u URL -k API_KEY -q "QUERY"

# Use environment variables
export UNRAID_URL="https://unraid.local/graphql"
export UNRAID_API_KEY="your-key"
./scripts/unraid-query.sh -q "{ online }"

# Format options
-f json    # Raw JSON (default)
-f pretty  # Pretty-printed JSON
-f raw     # Just the data (no wrapper)

Additional Resources

Reference Files

For detailed documentation, consult:

• references/endpoints.md - Complete list of all 27 API endpoints
• references/troubleshooting.md - Common errors and solutions
• references/api-reference.md - Detailed field documentation

Helper Scripts

• scripts/unraid-query.sh - Main GraphQL query tool
• scripts/dashboard.sh - Automated multi-server inventory reporter

Quick Command Reference

# System status
./scripts/unraid-query.sh -q "{ online metrics { cpu { percentTotal } } }"

# Disk health
./examples/disk-health.sh

# Array status
./scripts/unraid-query.sh -q "{ array { state } }"

# Read logs
./examples/read-logs.sh syslog 20

# Complete dashboard
./scripts/dashboard.sh

# List shares
./scripts/unraid-query.sh -q "{ shares { name } }"

# List containers
./scripts/unraid-query.sh -q "{ docker { containers { names state } } }"