# 查询 Grafana 工具连接

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```


查询当前工作区的 Grafana 工具连接状态。该接口不返回服务账号令牌。

```text
GET https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/tools/grafana/connect
```

## 调用前准备

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

## 请求参数

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 调用示例

```bash
curl "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/tools/grafana/connect" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

:::::
:::::{tab-item} 参数说明

### 路径参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `workspace_id` | string | 是 | 当前工作区 ID。 |

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": 0,
  "data": {
    "tool_id": "moi.grafana.tools",
    "status": "disconnected",
    "requires_reconnect": false
  }
}
```

```json
{
  "code": 0,
  "data": {
    "tool_id": "moi.grafana.tools",
    "grafana_url": "https://grafana.example.com",
    "credential_ref": "cred_01",
    "status": "connected",
    "connected_at": "2026-01-02T15:04:05Z",
    "requires_reconnect": false
  }
}
```

:::::
:::::{tab-item} 字段说明

成功时返回 `200`。未保存连接时，接口返回 `disconnected` 状态。



连接可用时：



响应字段如下。

::::{tab-set}
:::{tab-item} 通用字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer | 成功时为 `0`。 |

:::

:::{tab-item} 基本信息

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `tool_id` | string | Grafana 内置工具标识。 |
| `grafana_url` | string | 已保存的基础 URL；连接不可用时可能不返回。 |
| `status` | string | `connected`、`disconnected` 或 `needs_reconnect`。 |
| `credential_ref` | string | 凭据引用和连接时间；未连接时不返回。 |
| `connected_at` | string | 凭据引用和连接时间；未连接时不返回。 |
| `requires_reconnect` | boolean | 凭据失效或配置不可用时为 `true`。 |

:::
::::

:::::
::::::
:::::::

## 错误响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": 2,
  "message": "<错误信息>"
}
```

:::::
:::::{tab-item} 字段说明

### 常见 HTTP 错误

::::{tab-set}
:::{tab-item} 通用字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `400` | `2`（`INVALID_ARGUMENT`） | **常见原因：**工作区 ID 无效。**建议操作：**检查路径参数。 |
| `401` | `6`（`UNAUTHENTICATED`） | **常见原因：**缺少有效身份凭据。**建议操作：**检查 API Key。 |
| `403` | `5`（`PERMISSION_DENIED`） | **常见原因：**当前身份没有读取工具连接的权限。**建议操作：**检查工作区授权。 |
| `503` | `15`（`UNAVAILABLE`） | **常见原因：**Grafana 工具连接服务或授权依赖暂不可用。**建议操作：**稍后重试。 |

:::
::::

:::::
::::::
:::::::

## 后续操作

需要修改时[更新工具](update-tool.md)。返回列表时[查询工具标签](list-tool-tags.md)。