Health, info, check and backup over HTTP

Check that the server is alive, read the tables, disk use and health of a database, look for damage, make and list backups, watch deferred trigger queues, and read the server's memory, processor and settings.

• Category: HTTP API
• Keywords: health, /health, monitoring, uptime, api/info, table list, recovery_summary, damaged, last_lsn, api/check, scrub, damage, api/backup, api/backups, api/restore, restore while running, point_in_time, api/databases/swap, swap databases, backup_command, backup folder, --backups, last_backup, server_time_ms, auth_required, api/disk, disk usage, trash_bytes, wal_archive_bytes, api/trigger-queue, trigger queue, deferred trigger, oldest_pending_age_ms, zone_partition_skips, zone_block_skips, slice_reads, slice_cache_hits, slice_cache_bytes, KDB_SLICE_CACHE_MB, kdb_slice_reads_total, cache_pinned, cache_verify_checks, cache_verify_mismatches, rev_values, wal_archive_mb, web_dir, help_dir, skill_dir, metrics, /metrics, Prometheus, Grafana, slow queries, slow-query log, api/slow-queries, --slow-query-ms, KDB_SLOW_QUERY_MS, trash_purged_bytes
• See also: HTTP API overview, Backup, check, repair and restore, kdb info, check, repair, dump-file, Web console (health-box)

These routes tell you how the server and a database are doing. The web console uses them for its table list and health box.

• GET /health is for monitoring: it needs no login and never touches data.
• The other routes work on one database: db=<name> or the header X-KDB-Database (choosing the database).
• Backups go to the backup folder: _backups in the data folder unless --backups <folder> (or KDB_BACKUP_DIR, backup_dir in kdb.conf) names another (where the settings come from).

GET /health

Syntax:

GET /health

Answers when the server is running. Use it to check that KDB is up (a monitoring script, a load balancer, a start script that waits for the server).

• Status codes: 200; 503 while the server is stopping (drain). When the server does not run, there is no answer at all (the connection is refused).
• Notes: /health never needs a token or login, even on a server that has them. It does not open a database, so it stays fast when a database is busy. When every HTTP worker is busy with queries, /health does not wait in line behind them: a thread of its own answers it (plain HTTP; over https it waits for a worker as before).
• At start: the port answers within about a second, however many databases the data folder holds. Only the default database is opened at start; every other one opens when it is first used. A start script that must wait for the default database waits for "ready": true.

HTTP: Is the server alive?

GET /health

Response:

HTTP 200 (application/json)

{
  "status": "ok",
  "version": "0.2.0-dev",
  "server_time_ms": 1792647852082,
  "auth_required": false,
  "login": false,
  "tls": false,
  "ready": true,
  "standby": false
}

curl -s http://127.0.0.1:9900/health

# Wait until a server that is starting answers (at most 10 seconds).
foreach ($i in 1..50) {
  try { $h = Invoke-RestMethod http://127.0.0.1:9900/health; "KDB $($h.version) is up"; break }
  catch { Start-Sleep -Milliseconds 200 }
}

import requests

try:
    h = requests.get("http://127.0.0.1:9900/health", timeout=3).json()
    print("up, version", h["version"])
except requests.RequestException:
    print("KDB is down")

GET /api/info

Syntax:

GET /api/info[?db=<name>]

Everything about one database: its tables and columns, sizes, damage, what happened when it was opened, and the last backup.

• Status codes: 200; 401/403 login or role (needs read); 404 unknown database; 500 the database cannot be read.
• Notes: views, functions and procedures are not in tables[]; use SHOW VIEWS, SHOW FUNCTIONS and SHOW PROCEDURES with /exec.

HTTP: A small database: one table

Setup:

CREATE TABLE brokers (id INT PRIMARY KEY, name STRING NOT NULL);
INSERT INTO brokers VALUES (1, 'Keystone Securities'), (34, 'Vision Securities');

GET /api/info

Response:

HTTP 200 (application/json)

{
  "database": "demo",
  "dir": "kdb-data/demo",
  "version": "0.2.0-dev",
  "opened_ms": 1792647852097,
  "server_time_ms": 1792647852145,
  "last_lsn": 4,
  "data_files": 1,
  "data_bytes": 231,
  "tables": [
    {
      "name": "brokers",
      "kind": "relational",
      "partition": "NONE",
      "timestamp_column": "",
      "rows": 2,
      "bytes": 0,
      "columns": [
        {
          "name": "id",
          "type": "INT",
          "primary_key": true,
          "not_null": false,
          "computed": false,
          "references": ""
        },
        {
          "name": "name",
          "type": "STRING",
          "primary_key": false,
          "not_null": true,
          "computed": false,
          "references": ""
        }
      ],
      "create_sql": "CREATE TABLE brokers (\n  id INT PRIMARY KEY,\n  name STRING NOT NULL\n)"
    }
  ],
  "damaged": [],
  "recovery_summary": "manifest copy: -, last shutdown: clean\nreplayed 0 transactions after LSN 0, last LSN 0\nopened in 1 ms: manifest 1 ms, 0 files read 0 ms, log check 0 ms, replay 0 ms (0 transactions), clean-up 0 ms",
  "warning": "",
  "backup_dir": "./backups/demo",
  "last_backup": null,
  "auth_required": false,
  "read_only": false,
  "protection": {
    "statement_timeout_ms": 60000,
    "max_result_bytes": 1073741824,
    "max_groups": 5000000,
    "max_queries_per_user": 32,
    "safe_updates": false,
    "running": 1,
    "server_read_only": false,
    "audit": true
  },
  "backup_schedule": null,
  "backup_command": null,
  "timers": 0
}

$info = Invoke-RestMethod "http://127.0.0.1:9900/api/info?db=market"
"log LSN: $($info.last_lsn)   damaged files: $($info.damaged.Count)"
$info.tables | Select-Object name, kind, partition, timestamp_column, rows | Format-Table -AutoSize

const info = await (await fetch("http://127.0.0.1:9900/api/info?db=market")).json();
for (const t of info.tables) console.log(t.name, t.kind, t.rows, t.columns.map((c) => `${c.name} ${c.type}`).join(", "));

GET /api/disk

Syntax:

GET /api/disk[?db=<name>]

What one database takes on disk, part by part. The console's Keep data page shows it. It walks the trash folder, so it is a separate route and not part of /api/info.

• Status codes: 200; 401/403 login or role (needs read); 404 unknown database.
• Notes: see trash and versions for how to free the space.

HTTP: Disk use of a small database

Setup:

CREATE TABLE brokers (id INT PRIMARY KEY, name STRING NOT NULL);
INSERT INTO brokers VALUES (1, 'Keystone Securities'), (34, 'Vision Securities');

GET /api/disk

Response:

HTTP 200 (application/json)

{
  "database": "demo",
  "data_files": 1,
  "data_bytes": 231,
  "tail_files": 0,
  "tail_bytes": 0,
  "delta_files": 0,
  "delta_bytes": 0,
  "previous_files": 0,
  "previous_bytes": 0,
  "trash_folders": 0,
  "trash_bytes": 0,
  "wal_bytes": 1048640,
  "wal_archive_bytes": 0,
  "total_bytes": 1048871,
  "trash_purged_bytes": 0
}

GET /api/trigger-queue

Syntax:

GET /api/trigger-queue[?db=<name>][&trigger=<name>][&wait=<time>]

The queues of the database's deferred triggers, and every job that has not finished yet. Use it to see the lag after a load, or to wait until the work of a load is done.

Each queues object:

A job's status is waiting, running, done, skipped, failed, or blocked (waiting behind a failed job).

• Status codes: 200; 400 a wait that is not a time; 401/403 login or role (needs read); 404 unknown database, or trigger names no deferred trigger.
• Notes: GET /api/stats shows the same queues for every open database, under trigger_queues. A load can also wait for its own jobs: POST /write?...&wait=trigger (line protocol).

HTTP: One deferred trigger, after a load

Setup:

CREATE TABLE trades (id INT, qty INT);
CREATE TABLE seen (id INT);
CREATE TRIGGER copy_ids AFTER INSERT ON trades DEFERRED EXECUTE INSERT INTO seen SELECT id FROM NEW;
INSERT INTO trades VALUES (1, 10), (2, 20);

GET /api/trigger-queue?wait=10s

Response:

HTTP 200 (application/json)

{
  "queues": [
    {
      "trigger": "copy_ids",
      "table": "trades",
      "enabled": true,
      "timeout_ms": 0,
      "pending": 0,
      "oldest_pending_age_ms": 0,
      "running_job": null,
      "running_since_ms": 0,
      "failed_job": null,
      "failed_ms": 0,
      "last_done_job": 1,
      "failures": 0,
      "retries": 0,
      "refused_writes": 0
    }
  ],
  "jobs": []
}

HTTP: An unknown trigger

GET /api/trigger-queue?trigger=nope

Response:

HTTP 404 (application/json)

{"error": "deferred trigger 'nope' does not exist"}

POST /api/check

Syntax:

POST /api/check[?db=<name>]

Reads every block of every data file and of the log, and checks each against its checksum (a small number that changes when the data is damaged). Use it to find damage early.

• Status codes: 200 (also when damage is found: then ok is false); 401/403 login or role (needs admin on the database); 404 unknown database; 405 for GET.
• Notes: a big database takes time, because every file is read. When ok is false: stop the server and run kdb repair (check, repair, restore). CHECK TABLE name in SQL checks one table.

HTTP: Check the sample database (sample data: sample)

POST /api/check

Response:

HTTP 200 (application/json)

{
  "ok": true,
  "files_checked": 14,
  "bytes_checked": 77929,
  "wal_segments_checked": 1,
  "problems": [],
  "elapsed_us": 650
}

HTTP: GET is not allowed: checking is work for the server

GET /api/check

Response:

HTTP 405 (application/json)

{"error": "method GET is not allowed here"}

POST /api/backup

Syntax:

POST /api/backup[?db=<name>]

Makes a verified backup of the database while the server keeps running: it copies the files into a new folder and reads the copy back to check it.

• Status codes: 200; 400 backups are off (no backup folder is set; ...); 401/403 login or role (needs admin on the database); 404 unknown database; 500 disk trouble; 503 busy.
• Notes: other requests can go on while the backup runs. After each backup, old backups are removed: the newest of each of the last 7 days and of the last 4 weeks are kept (--keep-daily, --keep-weekly). BACKUP DATABASE in SQL (with POST /exec) does the same. A backup on the same disk is lost with that disk: a copy command copies each one off the server.

HTTP: Make a backup, then list the backups (sample data: sample)

POST /api/backup
###
GET /api/backups

Response:

POST /api/backup

HTTP 200 (application/json)

{
  "name": "20261022-054412-215",
  "dir": "./backups/demo/20261022-054412-215",
  "created_ms": 1792647852215,
  "created": "2026-10-22T05:44:12.215Z",
  "end_lsn": 30,
  "checkpoint_lsn": 30,
  "files": 9,
  "bytes": 194519
}

GET /api/backups

HTTP 200 (application/json)

{
  "backups": [
    {
      "name": "20261022-054412-215",
      "dir": "./backups/demo/20261022-054412-215",
      "created_ms": 1792647852215,
      "created": "2026-10-22T05:44:12.215Z",
      "end_lsn": 30,
      "checkpoint_lsn": 30,
      "files": 9,
      "bytes": 194519
    }
  ],
  "backup_dir": "./backups/demo",
  "point_in_time": {
    "possible": true,
    "from_ms": 1792647852215,
    "from": "2026-10-22T05:44:12.215Z",
    "from_backup": "20261022-054412-215",
    "log_first_lsn": 1,
    "why": "",
    "wal_archive_max_bytes": 1073741824
  }
}

# daily-backup.ps1: a backup and a check of a running server (run it with Task Scheduler).
$r = Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:9900/api/backup?db=market"
"backup $($r.name): $($r.files) files, $($r.bytes) bytes"
$c = Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:9900/api/check?db=market"
if (-not $c.ok) { Write-Output "CHECK FOUND A PROBLEM: $($c.problems -join '; ')"; exit 2 }
"check ok: $($c.files_checked) files"

# Linux cron, on a server with users: an admin user for that database.
curl -s -u admin:"$(cat /root/kdb-admin-password)" -X POST "http://127.0.0.1:9900/api/backup?db=shop"

GET /api/backups

Syntax:

GET /api/backups[?db=<name>]

Lists the backups of the database, newest first.

• Status codes: 200; 401/403 login or role (needs read); 404 unknown database.
• Notes: without a backup folder the list is empty. To restore one while the server runs, use POST /api/restore.

HTTP: No backups yet

GET /api/backups

Response:

HTTP 200 (application/json)

{
  "backups": [],
  "backup_dir": "./backups/demo",
  "point_in_time": {
    "possible": false,
    "from_ms": 0,
    "from": "",
    "from_backup": "",
    "log_first_lsn": 0,
    "why": "there is no backup yet: a point-in-time restore starts from one",
    "wal_archive_max_bytes": 1073741824
  }
}

import requests

for b in requests.get("http://127.0.0.1:9900/api/backups", params={"db": "market"}).json()["backups"]:
    print(b["created"], b["files"], "files", b["bytes"], "bytes")

POST /api/restore

Syntax:

POST /api/restore[?db=<name>]
body: {"as": "<new database>", "database": "<name>", "backup": "<backup name>", "until": "<time>" | "latest", "until_ms": <ms>}

Restores a backup of a database into a new database while the server runs. The database itself is not touched. See restore while the server runs.

• Needs: the user's own ROLE admin.
• Status codes: 200; 400 a missing or bad name, a bad until, or no backup older than until; 401; 403; 404 no such database, no backups, or no such backup; 409 the name is taken, or another restore is running; 500 the backup is damaged (pick another one) or a disk problem.
• Notes: one restore runs at a time. The source keeps taking reads and writes meanwhile; while its log is read, old log files stay in place. It is copied into a hidden folder first and only gets its name when complete, so nobody sees half a database. Each restore is in the audit log (event = 'restore').

HTTP: A backup, then a restore of it into a new database (sample data: sample)

POST /api/backup
###
POST /api/restore
Content-Type: application/json

{"as": "demo_restored"}
###
DELETE /api/databases/demo_restored

Response:

POST /api/backup

HTTP 200 (application/json)

{
  "name": "20261022-054412-388",
  "dir": "./backups/demo/20261022-054412-388",
  "created_ms": 1792647852388,
  "created": "2026-10-22T05:44:12.388Z",
  "end_lsn": 30,
  "checkpoint_lsn": 30,
  "files": 9,
  "bytes": 194519
}

POST /api/restore

HTTP 200 (application/json)

{
  "database": "demo_restored",
  "source": "demo",
  "backup": {
    "name": "20261022-054412-388",
    "dir": "./backups/demo/20261022-054412-388",
    "created_ms": 1792647852388,
    "created": "2026-10-22T05:44:12.388Z",
    "end_lsn": 30,
    "checkpoint_lsn": 30,
    "files": 9,
    "bytes": 194519
  },
  "until_ms": null,
  "used_log": false,
  "opened": true,
  "open_error": "",
  "notes": [
    "restored 9 data files from ./backups/demo/20261022-054412-388; the log (up to LSN 30) is replayed on first open"
  ],
  "took_ms": 98,
  "next": "check 'demo_restored', then POST /api/databases/swap {\"database\":\"demo\",\"with\":\"demo_restored\"} to put it in place, or DROP DATABASE demo_restored"
}

DELETE /api/databases/demo_restored

HTTP 200 (application/json)

{
  "name": "demo_restored",
  "dropped": true,
  "moved_to": "kdb-data/_trash/1792647852627-demo_restored"
}

HTTP: The name is taken

POST /api/backup
###
POST /api/restore
Content-Type: application/json

{"as": "demo_twice"}
###
POST /api/restore
Content-Type: application/json

{"as": "demo_twice"}

Response:

POST /api/backup

HTTP 200 (application/json)

{
  "name": "20261022-054412-423",
  "dir": "./backups/demo/20261022-054412-423",
  "created_ms": 1792647852423,
  "created": "2026-10-22T05:44:12.423Z",
  "end_lsn": 0,
  "checkpoint_lsn": 0,
  "files": 0,
  "bytes": 64
}

POST /api/restore

HTTP 200 (application/json)

{
  "database": "demo_twice",
  "source": "demo",
  "backup": {
    "name": "20261022-054412-423",
    "dir": "./backups/demo/20261022-054412-423",
    "created_ms": 1792647852423,
    "created": "2026-10-22T05:44:12.423Z",
    "end_lsn": 0,
    "checkpoint_lsn": 0,
    "files": 0,
    "bytes": 64
  },
  "until_ms": null,
  "used_log": false,
  "opened": true,
  "open_error": "",
  "notes": [
    "restored 0 data files from ./backups/demo/20261022-054412-423; the log (up to LSN 0) is replayed on first open"
  ],
  "took_ms": 44,
  "next": "check 'demo_twice', then POST /api/databases/swap {\"database\":\"demo\",\"with\":\"demo_twice\"} to put it in place, or DROP DATABASE demo_twice"
}

POST /api/restore

HTTP 409 (application/json)

{"error": "database 'demo_twice' already exists; restore into a new name, then swap or drop"}

POST /api/databases/swap

Syntax:

POST /api/databases/swap[?db=<name>]
body: {"database": "<name>", "with": "<other name>"}

The two databases trade their data, by renaming their folders. Everything KDB keeps by name stays with the name: users' rights, READ ONLY, the dialect, WAL_ARCHIVE, timers and pins. So after a restore into market_check, a swap of market with market_check puts the restored data under market for everyone who uses it, and the old data is in market_check.

• Needs: the user's own ROLE admin.
• Status codes: 200 {"swapped": true, "database", "with"}; 400 with missing, the same database twice, or a database served by its path; 401; 403; 404 no such database; 409 one of them is in use (an open PostgreSQL connection, a session, a running request), being opened, or dropped.
• Notes: both databases are closed for the swap and open again at their next use. The swap is in the audit log (event = 'swap database'). Swap again to undo it.

HTTP: Swap a database with a restored copy, then swap back

POST /exec
Content-Type: text/plain

CREATE TABLE t (a INT); INSERT INTO t VALUES (1)
###
POST /api/backup
###
POST /exec
Content-Type: text/plain

INSERT INTO t VALUES (2)
###
POST /api/restore
Content-Type: application/json

{"as": "demo_old"}
###
POST /api/databases/swap
Content-Type: application/json

{"with": "demo_old"}
###
POST /exec
Content-Type: text/plain

SELECT count(*) FROM t
###
POST /api/databases/swap
Content-Type: application/json

{"with": "demo_old"}
###
DELETE /api/databases/demo_old

Response:

POST /exec

HTTP 200 (application/json)

{
  "query": "CREATE TABLE t (a INT); INSERT INTO t VALUES (1)",
  "results": [
    {
      "statement": "CREATE TABLE t (\n  a INT\n)",
      "columns": [],
      "dataset": [],
      "count": 0,
      "truncated": false,
      "rows_affected": 0,
      "message": "table 't' created",
      "timings": {"parse_us": 20, "execute_us": 20219}
    },
    {
      "statement": "INSERT INTO t VALUES (1)",
      "columns": [],
      "dataset": [],
      "count": 0,
      "truncated": false,
      "rows_affected": 1,
      "message": "1 row(s) inserted",
      "timings": {"parse_us": 20, "execute_us": 3141}
    }
  ],
  "columns": [],
  "dataset": [],
  "count": 0,
  "timings": {"parse_us": 40, "execute_us": 23360}
}

POST /api/backup

HTTP 200 (application/json)

{
  "name": "20261022-054412-514",
  "dir": "./backups/demo/20261022-054412-514",
  "created_ms": 1792647852514,
  "created": "2026-10-22T05:44:12.514Z",
  "end_lsn": 4,
  "checkpoint_lsn": 4,
  "files": 2,
  "bytes": 707
}

POST /exec

HTTP 200 (application/json)

{
  "query": "INSERT INTO t VALUES (2)",
  "results": [
    {
      "statement": "INSERT INTO t VALUES (2)",
      "columns": [],
      "dataset": [],
      "count": 0,
      "truncated": false,
      "rows_affected": 1,
      "message": "1 row(s) inserted",
      "timings": {"parse_us": 19, "execute_us": 26}
    }
  ],
  "columns": [],
  "dataset": [],
  "count": 0,
  "timings": {"parse_us": 19, "execute_us": 26}
}

POST /api/restore

HTTP 200 (application/json)

{
  "database": "demo_old",
  "source": "demo",
  "backup": {
    "name": "20261022-054412-514",
    "dir": "./backups/demo/20261022-054412-514",
    "created_ms": 1792647852514,
    "created": "2026-10-22T05:44:12.514Z",
    "end_lsn": 4,
    "checkpoint_lsn": 4,
    "files": 2,
    "bytes": 707
  },
  "until_ms": null,
  "used_log": false,
  "opened": true,
  "open_error": "",
  "notes": [
    "restored 2 data files from ./backups/demo/20261022-054412-514; the log (up to LSN 4) is replayed on first open"
  ],
  "took_ms": 64,
  "next": "check 'demo_old', then POST /api/databases/swap {\"database\":\"demo\",\"with\":\"demo_old\"} to put it in place, or DROP DATABASE demo_old"
}

POST /api/databases/swap

HTTP 200 (application/json)

{"swapped": true, "database": "demo", "with": "demo_old"}

POST /exec

HTTP 200 (application/json)

{
  "query": "SELECT count(*) FROM t",
  "results": [
    {
      "statement": "SELECT count(*) FROM t",
      "columns": [
        {"name": "count(*)", "type": "LONG"}
      ],
      "dataset": [
        [1]
      ],
      "count": 1,
      "truncated": false,
      "rows_affected": 0,
      "message": "",
      "timings": {"parse_us": 27, "execute_us": 144}
    }
  ],
  "columns": [
    {"name": "count(*)", "type": "LONG"}
  ],
  "dataset": [
    [1]
  ],
  "count": 1,
  "timings": {"parse_us": 27, "execute_us": 144}
}

POST /api/databases/swap

HTTP 200 (application/json)

{"swapped": true, "database": "demo", "with": "demo_old"}

DELETE /api/databases/demo_old

HTTP 200 (application/json)

{
  "name": "demo_old",
  "dropped": true,
  "moved_to": "kdb-data/_trash/1792647852777-demo_old"
}

GET /api/stats

Syntax:

GET /api/stats

What the server is doing right now: the memory and processor of the process, the statements running this second, and the memory and cache counters of every open database. Everything here is a counter already in memory, so it is cheap enough to ask for every couple of seconds - no file is read and no database is opened to answer it. The Monitor page of the console shows it.

process:

limits - the CPU and memory the process may really use, and what KDB sized from them (self-tuning):

memory_limit - the memory limit for the whole process (--memory-limit):

Work out the processor share yourself from two readings: (cpu_ms2 - cpu_ms1) * 100 / (uptime_ms2 - uptime_ms1) is the percentage of one processor.

Each running object: id (the X-KDB-Request-Id the client sent, or ""), user ("" for the token), client, database, sql (the first 200 characters), started_ms, elapsed_ms, stopping. Cancel one with DELETE /exec/<id>; a statement with no id can only stop on its own timeout.

timers: every timer of the databases the caller may read, each as in GET /api/timers, with failures_24h (failed runs in about the last 24 hours).

Each opening_databases object says how far the open got. Opening a big database replays the log written after its last checkpoint, which over a slow disk takes minutes; the first request for it waits that long, and this list shows why and whether it is moving. Meanwhile other databases, /api/stats and GET /api/databases answer as usual.

Each databases object: name, busy and memory_warning (only when set, see below), checkpoint (below), opened_ms, last_lsn, loaded_bytes and memory_budget_bytes (table data in memory, against --memory), pending_bytes (changes not yet written to partition files), cache_bytes, cache_budget_bytes, cache_entries, cache_hits, cache_misses (--cache-mb), cache_verify_checks and cache_verify_mismatches (hits computed again and compared, with KDB_CACHE_VERIFY=1; see result cache), rev_values (values of rev columns that keep their own revision, all tables), cache_pinned (pinned statements whose result is in the cache now, see pinned queries), memory (below), open_cursors, read_only, tables - one object per table with name, rows, partitions, loaded_partitions, loaded_bytes and pending_rows - and materialized_views.

/api/stats never waits for a database. When a write or a checkpoint holds one, its object says "busy": true: the memory and cache numbers are live, and tables, the trigger queues, last_lsn and pending_bytes are from the last reading that got in. With snapshot reads on (since 2026-10-02), a long CALL or an open transaction no longer makes a database busy here: the rows of the tables it changes are counted on a snapshot, so they are the committed rows, fresh, and the open transaction is left alone. Only a checkpoint or a schema change still gives "busy": true. memory_warning is the memory warning of a database far bigger than --memory.

checkpoint - a checkpoint writing changes to partition files right now, or null. Over a slow disk one can take minutes; readers go on meanwhile.

Each materialized_views object says how far a materialized view is behind its table:

disk - what the database takes on disk, by kind, as it last measured it. Each open database measures once a minute, when it empties its old trash, so this costs the reply nothing: measured_ms (when; 0 = not yet), data_bytes, tail_files, tail_bytes, delta_files, delta_bytes (both part of data_bytes), previous_bytes, trash_bytes, trash_folders, wal_bytes, wal_archive_bytes, total_bytes, trash_purged_bytes (the fields of GET /api/disk).

memory - what this database holds, by kind. The sizes are estimates of the bytes KDB asked for.

• resident_bytes of the process is about budget_used_bytes + cache_used_bytes + the pending_bytes and index_bytes of every database + the memory of the statements running now + about 30 MB for the program. See memory.

• Needs: read. A user sees only the databases they may read, and only their own statements in running, because statement text can hold values; an admin sees everyone's.

• Status codes: 200; 401 without a login.

curl -s -H "Authorization: Bearer $KDB_TOKEN" http://127.0.0.1:9900/api/stats

GET /metrics

Syntax:

GET /metrics

The server's counters in the Prometheus text format, for Prometheus, Grafana Agent or any scraper. Every number is a counter the server keeps as it works, so a scrape never waits for a database lock and never slows a query.

• Needs: read. A user sees the per-database lines of the databases they may read. Send the token as for any route: Authorization: Bearer <token>.
• Notes: counters start at 0 when the server starts. Only open databases have per-database lines.

curl -s -H "Authorization: Bearer $KDB_TOKEN" http://127.0.0.1:9900/metrics

A Prometheus scrape job:

scrape_configs:
  - job_name: kdb
    authorization: { credentials: "<the token>" }
    static_configs: [{ targets: ["127.0.0.1:9900"] }]

GET /api/slow-queries

Syntax:

GET /api/slow-queries[?limit=100][&db=<name>]

Statements that took at least the slow-query threshold, newest first. They are kept on disk in <data folder>/_logs/slow_queries.jsonl (one JSON object per line), so they survive a restart. At 16 MB the file becomes slow_queries.1.jsonl and a new one starts; the one before that is removed. The Monitor shows the newest 20.

• Needs: read. A user who is not an admin sees only their own statements.
• Notes: the statement text is masked like the activity log's (a password or token literal becomes '***') and cut to 4,000 characters. Statements over HTTP and the PostgreSQL port both count.

curl -s -H "Authorization: Bearer $KDB_TOKEN" "http://127.0.0.1:9900/api/slow-queries?limit=10"

GET /api/settings

Syntax:

GET /api/settings

Where the server keeps its data, and whether that can be changed from here. The Settings page of the console shows it.

• Needs: the user's own ROLE admin.
• Status codes: 200; 401 without a login; 403 for any weaker role.

POST /api/settings

Syntax:

POST /api/settings
body: {"data_dir": "E:/kdb-data"}   (or data_dir=<folder> as a query or form field)
body: {"wal_archive_mb": 100}       (or both in one body)
body: {"backup_schedule": "daily 02:00", "backup_keep_daily": 14, "backup_keep_weekly": 8, "backup_dir": "E:/kdb_backups"}

Checks a folder and writes it to the settings file. A new folder takes effect at the next start, not at once, and nothing is moved: the databases in the old folder stay where they are. wal_archive_mb (0 = keep no old log) takes effect at once, for every database without its own ALTER DATABASE ... SET WAL_ARCHIVE. The backup settings take effect at the next start (backup_dir: a folder, off, or default for _backups in the data folder). backup_command is refused with 403: it runs a program on the server, so it is set in kdb.conf by hand, with --backup-command or KDB_BACKUP_COMMAND.

Before writing anything the server makes the folder if it is missing, writes and removes a probe file in it, and refuses a folder that is itself one database (it holds a _manifest.a) - the data folder is the one above those. A folder that fails any of these is a 400 with the reason, and the settings file is not touched.

• Needs: the user's own ROLE admin.
• Status codes: 200; 400 nothing to save, a folder that cannot be used, a wal_archive_mb that is not a whole number, or a bad backup schedule or count; 401; 403 (also for backup_command); 409 when the server has no settings file; 500 the file cannot be written.

POST /api/restart

Syntax:

POST /api/restart

Closes every database cleanly, then starts the server again in the same process, on the same port. No service manager, Docker restart policy or supervisor is needed.

The reply is sent before the server stops listening, so the caller always gets an answer. Statements that are running are stopped and open transactions rolled back, as at a normal shutdown. The server prints restarting..., then databases closed cleanly, then its usual banner; the restart is written to the audit log.

A folder saved in kdb.conf that cannot be used when the server comes back does not stop it: the server prints a warning and starts on the usual folder instead.

• Needs: the user's own ROLE admin.
• Status codes: 200; 401; 403; 409 when this server cannot restart itself (one database served by its path).