Skill Details
Back to Skills

/unraid

by jmagar

Query and monitor Unraid servers via the GraphQL API. Use when the user asks to

View on GitHub

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 } } }"