# UptimeScout API 文档

通过 REST、SDK 和 MCP 获取服务状态、区域信号及历史记录。构建仪表板，为 AI 助手提供清晰的可用性参考。

URL: https://uptimescout.com/zh/docs/

## REST

```sh
curl -G https://api.uptimescout.com/v1/status --data-urlencode "service=github" --data-urlencode "region=US" -H "Authorization: Bearer $EVELODE_LICENSE_KEY"
```

## 可用方法

- `GET /v1/services`: 搜索服务目录并翻页浏览。

- `GET /v1/status`: 读取单项服务当前已保存的状态。

- `GET /v1/statuses`: 通过一次请求读取多项服务的状态。

- `GET /v1/summary`: 汇总某个区域或所选服务的观测信号。

- `GET /v1/history`: 分页读取一段时间内保存的观测记录。

- `GET /v1/stats`: 计算已保存信号样本的占比，而非实际测得的运行时间。

- `GET /v1/incidents`: 列出信号明显的服务；这些情况并非已确认的全球性事件。

## 数据说明

UptimeScout 在后台存储各地区的观测数据。每条响应都包含观测时间和数据新鲜度信息。同一服务在不同地区可能呈现不同信号。

运行正常信号表示在该条已保存的样本中未观察到明显干扰。明显干扰或中断信号描述的是观测到的情况，并不代表已确认发生全球性事件。缺失或过期的观测记录状态未知。样本占比不是实际测得的运行时间百分比，也不代表 SLA。

各地区持续采集观测数据。请查看各项服务显示的最近观测时间和数据新鲜度，判断状态信息的时效性。

语言决定信息的呈现方式；观测地区决定数据描述的是哪个国家。您可以分别切换两者。页面经过翻译，并不意味着观测数据必然来自某个特定国家。

## 许可与请求限额

使用 Evelode 许可密钥作为 Bearer 令牌。请将密钥保存在服务器上，不要放入浏览器代码或公开代码仓库。只有成功的许可数据请求会计入额度。续订许可或更改套餐会启用新的额度；额度不会按自然月重置。年度套餐在整个年度许可期限内共用一个请求池。

## 连接 AI 助手

将 Streamable HTTP MCP 客户端连接到以下端点，并在 Authorization 标头中提供许可证密钥。七种只读工具可提供服务状态、区域信号和历史记录。许可证限制相同。

https://mcp.uptimescout.com

## 响应处理

读取数据前请先检查 HTTP 状态码：400 表示参数无效；401 或 403 表示身份验证或许可存在问题；409 表示请求期间许可权限发生变化；429 表示请求或速率超限；503 表示暂时无法使用。请遵循重试等待时间，避免短时间内反复重试。

OpenAPI: https://uptimescout.com/openapi.json
