Gatus API 使用详解

‍‍‌> 目标：逐条实测 Gatus v5.37.0 的全部 REST API（状态查询、历史结果、在线率、响应时间、外部推送、状态徽章、Prometheus 指标），请求与响应 JSON 均为实测照抄，可直接作为对接手册使用。已在 Ubuntu 22.04（x86_64，Gatus v5.37.0）实测通过。

一、环境信息

本篇所有 API 调用均在以下环境实测，回显逐条照抄：

操作系统：Ubuntu 22.04.5 LTS（x86_64）
Gatus 版本：v5.37.0（go version -m /usr/local/bin/gatus 实测确认）
API 基地址：http://127.0.0.1:8080（本机访问；远程访问换服务器 IP）
认证：默认未启用（启用 Basic 认证后的行为见 4.4 实测）
实测数据集：4 个端点（core_nginx-health、core_nginx-missing、external_quzuo-homepage、core_ext-agent），其中 nginx-health 曾按实验需要经历「条件失败→恢复」，ext-agent 由外部 API 推送产生数据
客户端工具：curl（7.81.0）、python3（格式化 JSON）

二、前置条件

2.1 端点与键名规则

Gatus 所有 API 都以「端点键（key）」定位端点，规则为 {group}_{name}（实测确认）：

端点配置	生成的 key
`name: nginx-health` + `group: core`	`core_nginx-health`
`name: quzuo-homepage` + `group: external`	`external_quzuo-homepage`
`name: ext-agent` + `group: core`（external-endpoints）	`core_ext-agent`

group 留空时 key 以 _name 开头（_nginx-health 形态）。URL 中 key 原样使用，无需转义（实测连字符与下划线均直接通过）。

2.2 通用响应特性（实测）

JSON 响应支持 gzip：带 Accept-Encoding: gzip 时服务端返回压缩内容（实测响应头含 Content-Encoding: gzip），curl --compressed 自动解压；
时间戳格式：结果时间为 RFC3339 纳秒级 UTC（2026-10-17T20:21:10.204459625Z 形态，实测）；
路径 404：key 不存在时返回空 JSON 数组或 404（视具体接口，逐条见下文实测）；
方法限制：查询接口仅支持 GET，实测 POST/DELETE 均返回 405 Method Not Allowed。

三、API 总览

Gatus 的 API 面向只读查询与外部状态推送，同端口随 Web UI 一起提供，实测整理如下：

类别	方法与路径	用途
状态查询	`GET /api/v1/endpoints/statuses`	全部端点的最近结果与事件（UI 仪表盘数据源）
状态查询	`GET /api/v1/endpoints/{key}/statuses`	单端点最近结果与事件
在线率	`GET /api/v1/endpoints/{key}/uptimes/{hours}h`	最近 N 小时在线率（0~1 浮点数）
响应时间	`GET /api/v1/endpoints/{key}/response-times/{hours}h`	最近 N 小时平均响应时间（毫秒）
状态徽章	`GET /api/v1/endpoints/{key}/health/badge.svg` 等	可嵌入 README 的 SVG 徽章
响应时间图表	`GET /api/v1/endpoints/{key}/response-times/{hours}h/chart.svg`	响应时间趋势 SVG 图
外部推送	`POST /api/v1/endpoints/{key}/external?success=&error=&duration=`	external-endpoints 状态推送（写接口）
指标	`GET /metrics`	Prometheus 格式指标（需配置 `metrics: true`）

API 无分页参数（statuses 默认返回最近一段结果，受 storage.maximum-number-of-results 控制数据量），无排序参数（按时间正序返回）。

四、认证与首次调用

4.1 无认证环境的首次调用

未配置 security 时 API 完全开放。第一次调用建议直接取全局状态：

curl -s "http://127.0.0.1:8080/api/v1/endpoints/statuses" | head -c 300

实测输出（节选，注意每个端点对象只有 group/key/name/results 四个字段，没有 events）：

[{"name":"ext-agent","group":"core","key":"core_ext-agent","results":[{"duration":10000000000,"success":true,"timestamp":"2026-10-17T20:16:02.440074618Z"},...]},...]

能返回 JSON 数组即 API 可用。

4.2 Basic 认证启用后的行为（实测）

配置 security.basic 后（生成 bcrypt 口令的完整流程见《Gatus 配置参数详解》），无凭据访问被拦截：

curl -s -D - "http://127.0.0.1:8080/api/v1/endpoints/statuses" | head -3
curl -s "http://127.0.0.1:8080/api/v1/endpoints/statuses"; echo

实测输出：

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"error":"Not Authenticated"}

携带正确凭据（实测用户 admin）恢复访问：

curl -s -D - -u admin:q1w2e3r4 "http://127.0.0.1:8080/api/v1/endpoints/statuses" -o /dev/null | head -1

实测输出：

HTTP/1.1 200 OK

API Key/Token 方式 Gatus 不提供，认证只有 Basic 与 OIDC 两种；程序对接建议在配置一个专用于 API 查询的账号。

4.3 方法与路径错误行为（实测）

curl -s -D - -X POST "http://127.0.0.1:8080/api/v1/endpoints/core_nginx-health/statuses" | head -4

实测输出：

HTTP/1.1 405 Method Not Allowed
Date: Sat, 17 Oct 2026 20:29:19 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 18

curl -s -o /dev/null -w '%{http_code}\n' -X DELETE "http://127.0.0.1:8080/api/v1/endpoints/core_nginx-health/statuses"
curl -s -o /dev/null -w '%{http_code}\n' "http://127.0.0.1:8080/api/v1/endpoints/badkey/uptimes/24h"

实测输出：

405
404

五、各 API 域详解

5.1 全部端点状态：GET /api/v1/endpoints/statuses

UI 仪表盘的数据源，返回全部端点的最近结果（实测注意：全局接口不含 events，事件序列走 5.2 的单端点接口）。

curl -s --compressed "http://127.0.0.1:8080/api/v1/endpoints/statuses" | head -c 120

实测输出（节选，数组按配置中端点定义顺序排列）：

[{"name":"ext-agent","group":"core","key":"core_ext-agent","results":[{"duration":10000000000,"success":true,"timestamp"

实测响应中 nginx-health 端点的完整对象（真实照抄）：

{
    "name": "nginx-health",
    "group": "core",
    "key": "core_nginx-health",
    "results": [
        {
            "status": 200,
            "hostname": "gatus-5370-target-nginx",
            "duration": 190929,
            "conditionResults": [
                {
                    "condition": "[STATUS] == 200",
                    "success": true
                },
                {
                    "condition": "[BODY].status == UP",
                    "success": true
                }
            ],
            "success": true,
            "timestamp": "2026-10-17T20:40:27.306642971Z"
        }
    ]
}

外部推送端点的结果对象更精简（实测 core_ext-agent，无 status/hostname/conditionResults）：

{
    "duration": 10000000000,
    "success": true,
    "timestamp": "2026-10-17T20:50:32.46688896Z"
}

字段语义（实测归纳）：

字段	含义
`results[].status`	HTTP 状态码（非 HTTP 探测为 0）
`results[].hostname`	探测目标 URL 的主机部分（实测原样返回配置的 URL 主机名，不展开为 IP）
`results[].success`	本次探测整体是否健康（全部条件通过）
`results[].duration`	耗时，纳秒（190929 ≈ 0.19 ms）
`results[].errors`	传输层失败原因（TLS 错误、超时等）；实测条件失败不写入该字段，只在 `conditionResults` 中体现
`results[].conditionResults`	逐条件判定明细；成功时 condition 保持配置原文（`[STATUS] == 200`）
`timestamp`	RFC3339 纳秒级 UTC（`2026-10-17T20:40:27.306642971Z` 形态）

💡 说明：results 数组默认返回最近若干条（上限即配置的 storage.maximum-number-of-results，默认 100），按时间正序排列；成功结果实测不含 errors 键（JSON 字段省略而非空数组）。

5.2 单端点状态：GET /api/v1/endpoints/{key}/statuses

结构同 5.1，只含单端点（实测 core_nginx-health）：

curl -s "http://127.0.0.1:8080/api/v1/endpoints/core_nginx-health/statuses"

实测响应最新一条结果（results 最后一个元素，照抄）：

{
  "status": 200,
  "hostname": "gatus-5370-target-nginx",
  "duration": 217018,
  "conditionResults": [
    {
      "condition": "[STATUS] == 200",
      "success": true
    },
    {
      "condition": "[BODY].status == UP",
      "success": true
    }
  ],
  "success": true,
  "timestamp": "2026-10-17T20:56:47.626304079Z"
}

单端点接口比全局接口多出的 events 数组（照抄实测值，覆盖了实验期两次真实故障与恢复）：

"events": [
  { "type": "START", "timestamp": "2026-10-17T20:08:55.607186461Z" },
  { "type": "HEALTHY", "timestamp": "2026-10-17T20:08:55.657186461Z" },
  { "type": "UNHEALTHY", "timestamp": "2026-10-17T20:20:08.531932474Z" },
  { "type": "HEALTHY", "timestamp": "2026-10-17T20:22:11.902327944Z" },
  { "type": "UNHEALTHY", "timestamp": "2026-10-17T20:53:31.175507544Z" },
  { "type": "HEALTHY", "timestamp": "2026-10-17T20:54:02.623694907Z" }
]

失败样例（实验期把条件临时改成 [STATUS] == 201 时的实测响应）。注意三点：没有 errors 键（条件失败不走 errors，errors 只在传输层失败时出现）；失败的 condition 会被渲染为 [STATUS] (实际值) == 期望值 形式；status 字段仍是实际响应码 200：

{
  "status": 200,
  "hostname": "gatus-5370-target-nginx",
  "duration": 221275,
  "conditionResults": [
    {
      "condition": "[STATUS] (200) == 201",
      "success": false
    },
    {
      "condition": "[BODY].status == UP",
      "success": true
    }
  ],
  "success": false,
  "timestamp": "2026-10-17T20:53:46.181148016Z"
}

不存在的 key 实测返回 404 与纯文本提示：

curl -s -o /tmp/ne.txt -w '%{http_code}\n' "http://127.0.0.1:8080/api/v1/endpoints/core_not-exist/statuses"
cat /tmp/ne.txt; echo

实测输出：

404
endpoint not found

5.3 在线率：GET /api/v1/endpoints/{key}/uptimes/{hours}h

返回最近 N 小时的在线率，响应不是 JSON 而是一个裸浮点数（实测确认，0~1）：

curl -s "http://127.0.0.1:8080/api/v1/endpoints/core_nginx-health/uptimes/24h"; echo
curl -s "http://127.0.0.1:8080/api/v1/endpoints/core_ext-agent/uptimes/24h"; echo
curl -s "http://127.0.0.1:8080/api/v1/endpoints/external_quzuo-homepage/uptimes/24h"; echo

实测输出：

0.859155
0.500000
0.941176

实测自洽性核对：ext-agent 共 2 条记录（1 次成功推送、1 次失败推送），24h 在线率 0.500000 与之吻合；quzuo-homepage 17 条中 1 条失败（早期 TLS 排障期），0.941176 = 16/17 完全一致。nginx-health 的 0.859155 反映了实验期条件失败的影响。

5.4 平均响应时间：GET /api/v1/endpoints/{key}/response-times/{hours}h

返回最近 N 小时平均响应时间，响应同样是裸数值，单位毫秒（实测确认）：

curl -s "http://127.0.0.1:8080/api/v1/endpoints/core_nginx-health/response-times/24h"; echo
curl -s "http://127.0.0.1:8080/api/v1/endpoints/core_ext-agent/response-times/24h"; echo

实测输出：

0
5000

实测解读：nginx-health 本机拨测耗时低于 1 ms，平均值四舍五入为 0；ext-agent 的 5000 来自两次外部推送的 duration=10s（10000 ms）与一次不带时长的失败推送平均。该接口适合做跨端点耗时对比，对超短耗时的本机探测不敏感。

5.5 外部状态推送：POST /api/v1/endpoints/{key}/external

external-endpoints 配置的端点由外部程序调用本接口推送状态，是 Gatus 唯一的写接口。鉴权用配置的 token，放 Authorization: Bearer 头（实测）。

成功推送：

curl -s -D - -X POST -H "Authorization: Bearer q1w2e3r4" \
  "http://127.0.0.1:8080/api/v1/endpoints/core_ext-agent/external?success=true&duration=10s"

实测输出（成功推送返回 200 且响应体为空）：

HTTP/1.1 200 OK
Date: Sat, 17 Oct 2026 20:50:53 GMT
Content-Length: 0

失败推送（带错误信息，实测推送后该端点在 UI/API 上转为 UNHEALTHY）：

curl -s -X POST -H "Authorization: Bearer q1w2e3r4" \
  "http://127.0.0.1:8080/api/v1/endpoints/core_ext-agent/external?success=false&error=agent%20connection%20timeout"

实测输出（同样返回空响应体）：

错误凭据（实测 401）：

curl -s -D - -X POST -H "Authorization: Bearer wrong-token" \
  "http://127.0.0.1:8080/api/v1/endpoints/core_ext-agent/external?success=true" | head -6

实测输出：

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"error":"Not Authenticated"}

推送后的数据可见性实测（statuses 中的完整结果，成功/失败/再次成功三次推送后）：

curl -s "http://127.0.0.1:8080/api/v1/endpoints/core_ext-agent/statuses" | python3 -m json.tool

实测响应（完整照抄）：

{
    "name": "ext-agent",
    "group": "core",
    "key": "core_ext-agent",
    "results": [
        {
            "duration": 10000000000,
            "success": true,
            "timestamp": "2026-10-17T20:16:02.440074618Z"
        },
        {
            "duration": 0,
            "errors": [
                "agent connection timeout"
            ],
            "success": false,
            "timestamp": "2026-10-17T20:16:03.006299512Z"
        },
        {
            "duration": 10000000000,
            "success": true,
            "timestamp": "2026-10-17T20:50:32.46688896Z"
        }
    ],
    "events": [
        {
            "type": "START",
            "timestamp": "2026-10-17T20:16:02.390074618Z"
        },
        {
            "type": "HEALTHY",
            "timestamp": "2026-10-17T20:16:02.440074618Z"
        },
        {
            "type": "UNHEALTHY",
            "timestamp": "2026-10-17T20:16:03.006299512Z"
        },
        {
            "type": "HEALTHY",
            "timestamp": "2026-10-17T20:50:32.46688896Z"
        }
    ]
}

💡 说明：外部推送产生的结果结构比主动探测精简——只有 duration/success/timestamp/errors 四个字段，没有 status/hostname/conditionResults（推送方自己负责判断健康逻辑）；duration 为纳秒（duration=10s 推送即 10000000000）；每次状态翻转都会产生对应 HEALTHY/UNHEALTHY 事件。

查询参数说明（实测有效）：

参数	取值	说明
`success`	`true`/`false`	推送的状态
`error`	任意文本（URL 编码）	失败原因，会原样出现在 `errors` 数组与 UI 上
`duration`	Go 时长格式（`10s`、`500ms`）	该次状态的耗时，纳入 response-times 统计

⚠️ 注意：key 必须用 external-endpoints 配置过的 {group}_{name}，token 必须与配置一致；推送会即时触发告警判定（失败推送等价于一次失败探测），heartbeat.interval 配置的心跳超时也会由此驱动。

5.6 状态徽章：health/badge.svg 与变体

徽章接口用于 README/文档嵌入，无需认证（公开状态页形态）。实测四类徽章：

健康状态徽章（SVG）：

curl -s "http://127.0.0.1:8080/api/v1/endpoints/core_nginx-health/health/badge.svg"

实测输出（完整 SVG）：

<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="105" height="20" role="img" aria-label="nginx-health:"><title>nginx-health: </title><g shape-rendering="crispEdges"><linearGradient id="1075s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="1075r"><rect width="105" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#1075r)"><rect width="71" height="20" fill="#555"/><rect x="71" width="34" height="20" fill="#4c1"/><rect width="105" height="20" fill="url(#1075s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="110" text-rendering="geometricPrecision"><text x="355" y="150" transform="scale(.1)" fill="#010101" fill-opacity=".3" textLength="610">nginx-health</text><text x="355" y="140" transform="scale(.1)" fill="#fff" textLength="610">nginx-health</text><text x="870" y="150" transform="scale(.1)" fill="#010101" fill-opacity=".3" textLength="240">UP</text><text x="870" y="140" transform="scale(.1)" fill="#fff" textLength="240">UP</text></g></svg>

shields.io 兼容格式（badge.shields）：

curl -s "http://127.0.0.1:8080/api/v1/endpoints/core_nginx-health/health/badge.shields"

实测输出：

{"schemaVersion":1,"label":"nginx-health","message":"UP","color":"brightgreen","isError":false}

在线率徽章（uptimes badge.svg，前 12 行）：

curl -s "http://127.0.0.1:8080/api/v1/endpoints/core_nginx-health/uptimes/24h/badge.svg" | head -12

实测输出（节选）：

<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="150" height="20" role="img" aria-label="nginx-health: 85.9%过去24小时"><title>nginx-health: 85.9%过去24小时</title><g shape-rendering="crispEdges">...

响应时间徽章（response-times badge.svg，前 12 行）：

curl -s "http://127.0.0.1:8080/api/v1/endpoints/core_nginx-health/response-times/24h/badge.svg" | head -12

实测输出（节选）：

<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="198" height="20" role="img" aria-label="平均响应时间 0ms"><title>平均响应时间 0ms</title><g shape-rendering="crispEdges">...

响应时间趋势图（chart.svg，前 8 行）：

curl -s "http://127.0.0.1:8080/api/v1/endpoints/core_nginx-health/response-times/24h/chart.svg" | head -8

实测输出（节选）：

<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 1280 300"><path  d="M 0 0
L 1280 0
L 1280 300
L 0 300
L 0 0" style="stroke-width:0;stroke:rgba(255,255,255,1.0);fill:rgba(255,255,255,0.0)"/><path  d="M 27 11
L 1195 11

徽章颜色阈值可按端点定制（endpoints[].ui.badge.response-time，默认 [50, 200, 300, 500, 750] 毫秒分档）。

5.7 Prometheus 指标：GET /metrics

需配置 metrics: true。实测响应头与指标（全量 16 条 gatus_ 指标照抄）：

curl -s -D - "http://127.0.0.1:8080/metrics" | head -4

实测输出：

HTTP/1.1 200 OK
Date: Sat, 17 Oct 2026 20:38:53 GMT
Content-Type: text/plain; version=0.0.4; charset=utf-8; escaping=underscores
Content-Length: 11302

curl -s "http://127.0.0.1:8080/metrics" | grep "^gatus_"

实测输出：

gatus_results_certificate_expiration_seconds{group="external",key="external_quzuo-homepage",name="quzuo-homepage",type="HTTP"} 7.035649907032556e+06
gatus_results_code_total{code="200",group="core",key="core_nginx-health",name="nginx-health",type="HTTP"} 44
gatus_results_code_total{code="200",group="external",key="external_quzuo-homepage",name="quzuo-homepage",type="HTTP"} 3
gatus_results_code_total{code="404",group="core",key="core_nginx-missing",name="nginx-missing",type="HTTP"} 11
gatus_results_connected_total{group="core",key="core_nginx-health",name="nginx-health",type="HTTP"} 44
gatus_results_connected_total{group="core",key="core_nginx-missing",name="nginx-missing",type="HTTP"} 11
gatus_results_connected_total{group="external",key="external_quzuo-homepage",name="quzuo-homepage",type="HTTP"} 3
gatus_results_duration_seconds{group="core",key="core_nginx-health",name="nginx-health",type="HTTP"} 0.000216646
gatus_results_duration_seconds{group="core",key="core_nginx-missing",name="nginx-missing",type="HTTP"} 0.001265084
gatus_results_duration_seconds{group="external",key="external_quzuo-homepage",name="quzuo-homepage",type="HTTP"} 0.175257058
gatus_results_endpoint_success{group="core",key="core_nginx-health",name="nginx-health",type="HTTP"} 1
gatus_results_endpoint_success{group="core",key="core_nginx-missing",name="nginx-missing",type="HTTP"} 1
gatus_results_endpoint_success{group="external",key="external_quzuo-homepage",name="quzuo-homepage",type="HTTP"} 1
gatus_results_total{group="core",key="core_nginx-health",name="nginx-health",success="true",type="HTTP"} 44
gatus_results_total{group="core",key="core_nginx-missing",name="nginx-missing",success="true",type="HTTP"} 11
gatus_results_total{group="external",key="external_quzuo-homepage",name="quzuo-homepage",success="true",type="HTTP"} 3

未开启 metrics 时 /metrics 返回 404（实测）。指标对接 Prometheus 的告警规则示例见《Gatus 运维手册》监控告警章节。

六、分页/过滤/排序通用约定

Gatus API 无显式分页与过滤参数，实测约定如下：

数据量控制在存储层完成：storage.maximum-number-of-results/maximum-number-of-events 决定每端点返回的历史条数上限（默认 100/50），需要更长历史就调大该值；
排序固定：results/events 按时间正序（旧→新），statuses 数组按配置文件中端点定义顺序返回（实测与配置顺序一致）；
无服务端字段过滤：只取某个端点用单端点接口，只取失败记录需客户端自行过滤 success=false；
时间范围：uptimes/{hours}h 与 response-times/{hours}h 的 hours 支持 24h/7d（7 天）等组合，超出存储保留期按已有数据计算。

七、常见问题

Q1：API 返回 401 Not Authenticated

说明已启用 security.basic 而请求未带凭据。curl 用 -u user:pass，或请求头 Authorization: Basic <base64(user:pass)>。程序对接建议专门建一个只读用途的账号（Gatus 无角色细分，任何账号都是全权限）。

Q2：/metrics 返回 404

配置里没有 metrics: true。加上后热重载即生效（实测），无需重启。

Q3：statuses 里 results 太少/太多

数量由 storage.maximum-number-of-results 决定（默认 100）。调大注意 SQLite 文件增长与清理周期（实测详见《Gatus 配置参数详解》存储一节）。

Q4：外部推送一直 401

核对三点：key 是否为 external-endpoints 配置的 {group}_{name} 组合（普通 endpoints 的 key 推送无效且 401）；token 与配置完全一致；请求头格式为 Authorization: Bearer <token>（实测 wrong-token 返回 {"error":"Not Authenticated"}）。

Q5：想拿到某端点的完整历史结果

statuses 接口只给存储保留范围内的最近结果。更长历史直接读 SQLite（endpoint_results 表，字段结构见《Gatus 配置参数详解》），或接 Prometheus 指标做长期曲线。

八、参考链接

官方 API 文档：https://gatus.io/docs/api
徽章与状态页文档：https://gatus.io/docs/badges
官方 README（external-endpoints 推送协议）：https://github.com/TwiN/gatus#external-endpoints
本站配套：《Gatus 配置参数详解》《Gatus 运维手册》《Gatus Docker Compose 部署指南》