跳到主要内容

数据查询 API

本文档列出了北极星（专业版）数据查询接口的详细说明，包括接口地址、请求参数、返回结果等。

提示

概述​

北极星数据查询 API 提供以下功能：

  • 实时数据查询：查询消息量、服务端 API 调用量、用户在线数等实时统计数据，数据延迟不超过 120 秒
  • T+1 数据查询：查询前一天的离线统计数据，在当天 10:00 后可查询前一天的数据

关于数据查询接口的概念介绍、开通方式、准备工作等，请参考北极星（专业版）数据查询接口介绍。

接口鉴权​

获取 API Key​

调用数据查询接口前，请先获取 API Key。关于如何获取 API Key 的详细步骤，请参考获取 API Key。

设置鉴权​

获取 API Key 后，在请求的 Header 中添加以下参数进行鉴权：

参数名类型位置说明
AuthorizationstringHeaderAPI Key，格式为 sk_ 开头的字符串

示例：

JSON
Authorization: sk_AIX8xIPL3FGg1TFDsuRiJhJ9PixpqOhEERdVacJ3SXXX

请求方法​

POST：https://数据中心域名/im/statistics/get

签名规则：所有数据查询接口请求均需要进行鉴权，详见接口鉴权。

请求域名​

根据您的应用所在数据中心，使用对应的请求域名：

数据中心请求域名
北京（国内数据中心）https://data.rong-api.com
新加坡https://data.sg-light-api.com
沙特https://data.sau-light-api.com
俄勒冈https://data.us-light-api.com

正文参数​

HTTP 请求正文数据格式为 application/json，支持以下参数：

参数名含义类型必传示例备注
queryType查询类型String是api_usage固定枚举值，不可为空。可选值请参考实时查询数据项和 T+1 数据项
timestamp事件时间Bigint否1747117740000毫秒级时间戳。为空时查询最近的数据

请求示例​

HTTP
POST /im/statistics/get HTTP/1.1
Host: data.rong-api.com
Authorization: sk_AIX8xIPL3FGg1TFDsuRiJhJ9PixpqOhEERdVacJ3XXX
Content-Type: application/json

{"queryType": "active_user_all", "timestamp": 1747193100000}

返回结果​

HTTP 响应正文包含具有以下结构的 JSON 对象：

返回值返回类型说明
codeNumber返回码，10000 表示请求成功。
dataArray查询结果数据，包含您请求的统计数据。具体字段根据 queryType 的不同而有所差异，详见各查询类型的字段说明。
fieldsObject字段说明（通常为 null）。
msgString错误信息（成功时为 null）。

实时查询数据项（queryType）​

实时查询数据项支持查询最近的数据，数据延迟不超过 120 秒。

api_usage​

含义：统计指定自然分钟内（如 12:00:00 到 12:00:59），客户调用融云服务端 API 的总调用次数。

统计频率：1 分钟。即每 1 分钟输出一批统计结果。

最大延迟：120 秒。即 12:00:00-12:00:59 的数据，保证于 12:03:00 前就绪。

字段含义：

字段名含义类型备注
app_keyApp Keystring应用的唯一标识
server_ts事件时间bigint自然分钟的起点（毫秒级时间戳）
api_name接口名称string服务端 API 接口路径
total总调用量bigint该分钟内该接口的总调用次数
success调用成功量bigint该分钟内该接口的成功调用次数
fail调用失败量bigint该分钟内该接口的失败调用次数
peak_second秒峰值bigint该分钟内接口调用的秒峰值

数据示例：

JSON
返回结果示例
{
    "code": 10000,
    "data": [
        {
            "server_ts": 1747117740000,
            "fail": 0,
            "total": 6,
            "app_key": "c9kqb3rdkbb8j",
            "api_name": "/user/getToken.json",
            "success": 6,
            "peak_second": 6
        }
    ],
    "fields": null,
    "msg": null
}

api_error​

含义：统计指定自然分钟内（如 12:00:00 到 12:00:59），客户调用融云服务端 API 时，返回异常的总次数。

统计频率：1 分钟。即每 1 分钟输出一批统计结果。

最大延迟：120 秒。即 12:00:00-12:00:59 的数据，保证于 12:03:00 前就绪。

字段含义：

字段名含义类型备注
app_keyApp Keystring应用的唯一标识
server_ts事件时间bigint自然分钟的起点（毫秒级时间戳）
api_name接口名称string服务端 API 接口路径
http_codeHTTP 错误码bigintHTTP 状态码
error_codeAPI 错误码bigint融云 API 错误码
total总调用量bigint该分钟内该接口的错误调用次数

数据示例：

JSON
返回结果示例
{
    "code": 10000,
    "data": [
        {
            "server_ts": 1747193100000,
            "total": 1,
            "app_key": "c9kqb3rdkbb8j",
            "http_code": 400,
            "api_name": "/ultragroup/channel/create.json",
            "error_code": 1002
        }
    ],
    "fields": null,
    "msg": null
}

msg_usage_up​

含义：统计指定自然分钟内（如 12:00:00 到 12:00:59），指定应用所有上行消息的累加总量。

统计频率：1 分钟。即每 1 分钟输出一批统计结果。

最大延迟：120 秒。即 12:00:00-12:00:59 的数据，保证于 12:03:00 前就绪。

字段含义：

字段名含义类型备注
app_keyApp Keystring应用的唯一标识
server_ts事件时间bigint自然分钟的起点（毫秒级时间戳）
platform平台string客户端平台，如 Android、iOS 等
channel渠道类型bigint1：单聊；2：群聊；4：聊天室；10：超级群
object_name消息类型string消息类型标识
country国家string用户所在国家
province省份string用户所在省份
total总调用量bigint该分钟内该类型消息的上行总量

数据示例：

JSON
返回结果示例
{
    "code": 10000,
    "data": [
        {
            "server_ts": 1747193100000,
            "country": "中国",
            "total": 1,
            "app_key": "c9kqb3rdkbb8j",
            "province": "北京市",
            "object_name": "T",
            "channel": 1,
            "platform": "Android"
        },
        {
            "server_ts": 1747193100000,
            "country": "中国",
            "total": 1,
            "app_key": "c9kqb3rdkbb8j",
            "province": "北京市",
            "object_name": "RC:RcCmd",
            "channel": 1,
            "platform": "iOS"
        }
    ],
    "fields": null,
    "msg": null
}

msg_usage_server​

含义：统计指定自然分钟内（如 12:00:00 到 12:00:59），指定应用所有分发消息的累加总量。

统计频率：1 分钟。即每 1 分钟输出一批统计结果。

最大延迟：120 秒。即 12:00:00-12:00:59 的数据，保证于 12:03:00 前就绪。

字段含义：

字段名含义类型备注
app_keyApp Keystring应用的唯一标识
server_ts事件时间bigint自然分钟的起点（毫秒级时间戳）
platform平台string客户端平台，如 Android、iOS 等
channel渠道类型bigint1：单聊；2：群聊；4：聊天室；10：超级群
object_name消息类型string消息类型标识
country国家string用户所在国家
province省份string用户所在省份
total总调用量bigint该分钟内该类型消息的分发总量

数据示例：

JSON
返回结果示例
{
    "code": 10000,
    "data": [
        {
            "server_ts": 1747193100000,
            "country": "中国",
            "total": 1,
            "app_key": "c9kqb3rdkbb8j",
            "province": "北京市",
            "channel": 1,
            "platform": "Android"
        },
        {
            "server_ts": 1747193100000,
            "country": "中国",
            "total": 60,
            "app_key": "c9kqb3rdkbb8j",
            "province": "北京市",
            "channel": 1,
            "platform": "iOS"
        }
    ],
    "fields": null,
    "msg": null
}

msg_usage_down​

含义：统计指定自然分钟内（如 12:00:00 到 12:00:59），指定应用所有下行消息的累加总量。

统计频率：1 分钟。即每 1 分钟输出一批统计结果。

最大延迟：120 秒。即 12:00:00-12:00:59 的数据，保证于 12:03:00 前就绪。

字段含义：

字段名含义类型备注
app_keyApp Keystring应用的唯一标识
server_ts事件时间bigint自然分钟的起点（毫秒级时间戳）
platform平台string客户端平台，如 Android、iOS 等
channel渠道类型bigint1：单聊；2：群聊；4：聊天室；10：超级群
object_name消息类型string消息类型标识
country国家string用户所在国家
province省份string用户所在省份
total总调用量bigint该分钟内该类型消息的下行总量

数据示例：

JSON
返回结果示例
{
    "code": 10000,
    "data": [
        {
            "server_ts": 1747193100000,
            "country": "中国",
            "total": 1,
            "app_key": "c9kqb3rdkbb8j",
            "province": "北京市",
            "channel": 1,
            "platform": "Android"
        },
        {
            "server_ts": 1747193100000,
            "country": "中国",
            "total": 60,
            "app_key": "c9kqb3rdkbb8j",
            "province": "北京市",
            "channel": 1,
            "platform": "iOS"
        }
    ],
    "fields": null,
    "msg": null
}

active_user_all​

含义：统计指定自然 5 分钟内（如 12:00:00 到 12:04:59），指定应用所有连接到融云服务器的用户去重数量。

统计频率：5 分钟。即每 5 分钟输出一批统计结果。

最大延迟：120 秒。即 12:00:00-12:04:59 的数据，保证于 12:07:00 前就绪。

字段含义：

字段名含义类型备注
app_keyApp Keystring应用的唯一标识
server_ts事件时间bigint自然分钟的起点（毫秒级时间戳）
online_count同时在线人数bigint该 5 分钟内连接到服务器的用户去重数量

数据示例：

JSON
返回结果示例
{
    "code": 10000,
    "data": [
        {
            "server_ts": 1747641000000,
            "online_count": 37,
            "app_key": "c9kqb3rdkbb8j"
        }
    ],
    "fields": null,
    "msg": null
}

active_user_chatroom​

含义：统计指定自然 5 分钟内（如 12:00:00 到 12:04:59），指定应用所有使用融云聊天室服务的用户去重数量。

统计频率：5 分钟。即每 5 分钟输出一批统计结果。

最大延迟：120 秒。即 12:00:00-12:04:59 的数据，保证于 12:07:00 前就绪。

字段含义：

字段名含义类型备注
app_keyApp Keystring应用的唯一标识
server_ts事件时间bigint自然分钟的起点（毫秒级时间戳）
online_count同时在线人数bigint该 5 分钟内使用聊天室服务的用户去重数量

数据示例：

JSON
返回结果示例
{
    "code": 10000,
    "data": [
        {
            "server_ts": 1747638600000,
            "online_count": 1,
            "app_key": "c9kqb3rdkbb8j"
        }
    ],
    "fields": null,
    "msg": null
}

active_user​

含义：统计指定自然分钟内（如 12:00:00 到 12:00:59），指定应用所有收发过融云信令的用户去重数量。

统计频率：1 分钟。即每 1 分钟输出一批统计结果。

最大延迟：120 秒。即 12:00:00-12:00:59 的数据，保证于 12:03:00 前就绪。

字段含义：

字段名含义类型备注
app_keyApp Keystring应用的唯一标识
server_ts事件时间bigint自然分钟的起点（毫秒级时间戳）
platform平台string客户端平台，如 Android、iOS 等
country国家string用户所在国家
province省份string用户所在省份
online_count同时在线数bigint该分钟内收发过信令的用户去重数量

数据示例：

JSON
返回结果示例
{
    "code": 10000,
    "data": [
        {
            "server_ts": 1747193100000,
            "online_count": 2,
            "country": "中国",
            "app_key": "c9kqb3rdkbb8j",
            "province": "北京市",
            "platform": "Android"
        },
        {
            "server_ts": 1747193100000,
            "online_count": 3,
            "country": "中国",
            "app_key": "c9kqb3rdkbb8j",
            "province": "北京市",
            "platform": "iOS"
        }
    ],
    "fields": null,
    "msg": null
}

T+1 数据项（queryType）​

T+1 数据项支持查询前一天的离线统计数据。

说明
  • 数据统计功能于 2025 年 12 月 26 日上线，可查询 26 日后的数据
  • 离线数据在当天 10:00 后可查询前一天的数据
  • 例如：2025-12-26 10:00:00 后，可查询 2025-12-25 的数据

app_online_info​

含义：统计指定自然天内（如 2025-12-26 00:00:00），指定应用用户相关信息的统计。

统计频率：1 天。即每 1 天输出一批统计结果。

最大延迟：10 小时。即 2025-12-26 10:00:00 后，可查询 2025-12-25 的数据。

字段含义：

字段名含义类型备注
app_keyApp Keystring应用的唯一标识
data_date事件时间bigint自然天，格式为 YYYYMMDD（如 20251225）
peak_online_count同时在线数峰值bigint该天内同时在线用户数的峰值
add_count新增用户数bigint该天内新增的用户数量
active_count活跃用户数bigint该天内有活动的用户数量

数据示例：

JSON
返回结果示例
{
    "code": 10000,
    "data": [
        {
            "app_key": "aaaaaaaa",
            "data_date": 20251202,
            "peak_online_count": 2,
            "add_count": 1,
            "active_count": 1
        }
    ],
    "fields": null,
    "msg": null
}

app_msg_info​

含义：统计指定自然天内（如 2025-12-26 00:00:00），指定应用消息用量相关信息的统计。

统计频率：1 天。即每 1 天输出一批统计结果。

最大延迟：10 小时。即 2025-12-26 10:00:00 后，可查询 2025-12-25 的数据。

字段含义：

字段名含义类型备注
app_keyApp Keystring应用的唯一标识
data_date事件时间bigint自然天，格式为 YYYYMMDD（如 20251225）
channel会话类型bigint1：单聊；2：群聊；4：聊天室；6：系统消息；10：超级群；100：消息订阅状态通知；104：聊天室 KV
up_count总上行bigint该天内该会话类型的上行消息总量
server_count总分发bigint该天内该会话类型的消息分发总量
down_count总下行bigint该天内该会话类型的下行消息总量

数据示例：

JSON
返回结果示例
{
    "code": 10000,
    "data": [
        {
            "app_key": "aaaaaaaa",
            "channel": 1,
            "up_count": 100,
            "server_count": 100,
            "down_count": 1000,
            "data_date": 20251202
        }
    ],
    "fields": null,
    "msg": null
}

常见问题​

接口返回错误码​

接口返回的错误码说明：

错误码说明解决方案
10000请求成功-
其他错误码请求失败请检查 API Key 是否正确，或联系技术支持

数据查询时间范围​

  • 实时数据：可查询最近的数据，timestamp 参数为空时返回最近的数据
  • T+1 数据：可查询前一天的数据，需在当天 10:00 后查询

API Key 权限​

请确保您的 API Key 具有查询权限。如遇到权限问题，请联系技术支持。