指标定义

返回某个指标的完整定义：它在数什么、返回什么形态、能按哪些维度分组、有哪些口径上的注意事项。

出数前建议先调它——尤其是比例类指标，分母口径直接影响你如何解读结果。

请求示例

Python + requests

import requests

url = "https://open.cli.im/api/v2/rpc/metrics/get"
data = {"metric": "plan_task_completion_ratio"}
headers = {
    "Authorization": "Bearer <你的API Key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=data, headers=headers)
print(response.text)

curl

curl -X POST 'https://open.cli.im/api/v2/rpc/metrics/get' \
  -H 'Authorization: Bearer <你的API Key>' \
  -H 'Content-Type: application/json' \
  -d '{"metric": "plan_task_completion_ratio"}'

请求参数

参数	类型	必填	说明
metric	string	是	指标名，从 指标目录 的 metrics[].name 里取

完整返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "result": {
      "layer": "L0.5",
      "definition": {
        "name": "plan_task_completion_ratio",
        "title": "周期任务按期完成占比",
        "description": "周期计划生成的任务里，已完成（含逾期补做）的占比。分母是「应做且未被跳过」的任务数。",
        "format": "ratio",
        "layer": "L0.5",
        "applicability": "has_cycle_plans",
        "dimensions": ["plan_target_form", "cycle_type", "month", "plan"],
        "limitations": [
          "分母 = 应做任务数 − 被跳过任务数。",
          "分子含逾期补做，不区分是否按时——要区分请看 breakdown。",
          "还没到期的任务计在分母里，时间窗越靠近当下、比例越低，属正常现象。"
        ]
      }
    },
    "next_actions": [
      {
        "tool": "query_metrics",
        "hint": "按这个口径出数（时间窗必填；可用维度见 definition.dimensions）"
      }
    ]
  }
}

响应结构

路径	类型	说明
data.result.definition.name	string	指标名（metrics/query 的 metric 参数值）
data.result.definition.format	string	返回形态：integer 计数；ratio 比例（结果会附分子分母）
data.result.definition.applicability	string	适用条件：has_records 有记录即可；has_cycle_plans 需要组织配置了周期计划
data.result.definition.dimensions[]	array	出数时 group_by 可用的维度
data.result.definition.limitations[]	array	口径与注意事项，逐条读完再解读数字

错误响应

指标名不存在时：

{
  "code": 400,
  "message": "metric_not_found: 没有名为「xxx」的口径。用 list_metrics 看这个组织当前可用的量。",
  "data": {}
}

其余错误码定义见：错误码说明。