服务端集成 · 报表查询 · 查询导出进度

说明如何通过 Gravity Engine OpenAPI 查询用户行为事件导出任务的进度、结果与失败信息，涵盖认证、请求参数、筛选条件和返回字段。

引力引擎支持使用 API 方式直接导出应用内用户行为事件，导出用户行为事件接口会返回导出任务的任务 ID，您可以根据此 ID 查询事件导出任务进度。

在开始对接此接口前，建议您先阅读数据规则章节，在熟悉引力引擎的数据格式与数据规则后，再阅读本指南进行对接。

申请引力开发者应用

在正式接入本接口之前，您需要在引力后台-引力开发者页面申请引力开发者应用，提交后请在该页面查看审核和启用状态，审核通过并启用后，再调用本接口。

创建好开发者应用之后，请复制 app_key 参数，并发送给研发同学以供后续接口调用使用。

接口限频

默认接口限频：每 10 秒 100 次。接口限频按开发者应用维度统计，即同一个 app_key 下的应用共用同一套频次限制。如果开发者绑定应用过多导致频繁触发限频，请联系引力运营评估后提升限频等级。

接口信息

接口地址

https://api-insight.gravity-engine.com/openapi/api/v1/download/event/query_result/

请求方法

POST

请求参数

字段	类型	描述
Authorization	string	具体如何生成，请参考【签名生成】

Body 参数

字段	必填	参数类型	描述
`task_id`	Y	string	应用事件导出的任务 ID
`sign`	Y	string	签名，详情请参考【签名生成】

请求示例

curl 'https://api-insight.gravity-engine.com/openapi/api/v1/download/event/query_result/' \
-H 'Content-Type: application/json' \
-H 'Authorization: YOUR_AUTHORIZATION' \
-d '{
    "sign": "YOUR_SIGN",
    "task_id": "e69217feac324e4eb7c4b9c0a860711a"
}'

响应参数

字段	描述
`status`	导出作业的状态码，数字类型。取值范围：`1` 处理中、`2` 处理完成、`3` 处理失败、`4` 取消下载任务、`5` 过期
`progress`	任务导出进度。取值范围：0-100
`download_url`	导出文件的下载链接，文件会保存 3 天，3 天后过期删除
`message`	任务附加信息；任务失败时结合该字段排查

响应示例

{
    "data": {
        "task_id": "56b98c5a9a774e458db441d7e9885972",
        "status": 2,
        "progress": 100,
        "download_url": "https://gravity-client-resource.oss-cn-hangzhou.aliyuncs.com/264832/excels/事件导出-267493-2025-10-31_12-17-55.csv.gz",
        "message": "{}"
    },
    "extra": null,
    "code": 0,
    "msg": "成功"
}

后续处理

status=1：任务仍在处理，间隔查询，避免高频轮询；接口响应成功不代表导出完成。
status=2：确认 download_url 非空后下载文件，并在文件保留期内保存到您的业务存储。
status=3、4 或 5：分别表示失败、取消或过期，应停止轮询；失败时查看返回的 message 并记录 task_id。确需重新导出时，再创建新任务。

下载链接用于获取导出数据，请按业务数据权限保管。每次查询仍需根据实际 body 生成签名与认证信息。

查询导出进度