> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 查询漏斗流失驱动因素

> 解释计数单位为何在某一步到下一步之间流失：因素、后续页面、路径与示例会话。

## 限制说明

| 项目 | 说明 |
| - | - |
| 速率限制 | 每个账户 **200 次/分钟**；**10 次/秒** |
| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |

## 使用说明

* `start_time` 与 `end_time` 为 Unix 毫秒时间戳。两者都省略时取最近 7 天；超过 14 天会返回 `InvalidParameter`。
* 调用方需对 `application_id` 有读权限；无权访问的私有应用数据不参与统计。
* `from_step` 从 1 开始，且必须存在下一步。
* 因素按区分转化与流失的能力排序；`low_sample=true` 表示该因素样本过少、不足以得出结论。
* `flow` 中 `to` 为空表示单位离开站点，为 `*` 表示去了该层前几名之外的页面。


## OpenAPI

````yaml /api-reference/rum.openapi.zh.json post /rum/funnel/drivers
openapi: 3.1.0
info:
  description: >-
    Flashduty 事件管理平台的公开 HTTP API —— 覆盖故障、通知模板、协作空间、值班排班、监控、RUM、以及平台管理。每次调用都需在
    query 中携带 `app_key`，该 key 在 Flashduty 控制台 我的 → APP Key 中创建（也可放在请求头
    `Fd-App-Key` 中）。所有响应使用统一结构：成功时为 `{ request_id, data }`，失败时为 `{ request_id,
    error }`。
  title: Flashduty 开放 API
  version: 1.0.0
servers:
  - description: Flashduty Open API
    url: https://api.flashcat.cloud
security:
  - AppKeyAuth: []
tags:
  - description: 管理前端性能监控（RUM）应用。
    name: RUM/应用管理
  - description: 对 RUM 事件数据执行分析查询。
    name: RUM/RUM 数据查询
  - description: 查询和管理 RUM 异常追踪 Issue 及预设严重性规则。
    name: RUM/RUM 问题跟踪
  - description: 查询 RUM 自定义字段及其值分布，用于构建分析过滤条件。
    name: RUM/RUM 自定义字段
  - description: 管理和查询用于 Browser、Android、iOS 错误符号化的 RUM Sourcemap 文件。
    name: RUM/RUM Sourcemap
  - description: 查询 RUM 会话的回放元数据与录制分段。
    name: RUM/RUM 会话回放
  - description: 配置和查看决定 RUM 应用采集哪些错误的规则，并可查看其编辑历史。
    name: RUM/错误采集规则
  - description: 管理按应用配置的预设严重性规则，用于为匹配的前端错误指定严重级别，并管理其评估顺序与变更历史。
    name: RUM/Issue 预设严重性规则
  - description: 查询账户的 RUM 资源记录及当前用量。
    name: RUM/资源
  - description: 创建和管理 RUM 自定义仪表盘及其版本历史与回收站。
    name: RUM/仪表盘
  - description: 定义和查看把原始 RUM 动作聚合为「行为事件」的规则。
    name: RUM 行为事件
  - description: 基于 RUM 会话与访客分析转化漏斗：结果、趋势、维度拆分、流失原因与页面流向。
    name: RUM 漏斗分析
  - description: 读取页面热力图：元素排行、点击坐标、滚动深度，以及用作背景的回放帧。
    name: RUM 热力图
paths:
  /rum/funnel/drivers:
    post:
      tags:
        - RUM 漏斗分析
      summary: 查询漏斗流失驱动因素
      description: 解释计数单位为何在某一步到下一步之间流失：因素、后续页面、路径与示例会话。
      operationId: rum-funnel-read-drivers
      requestBody:
        content:
          application/json:
            example:
              application_id: app_3fK9mQ2xLp7VbN4cR8dW1y
              definition:
                filters:
                  - field: device_type
                    values:
                      - desktop
                steps:
                  - kind: page
                    label: Cart
                    page:
                      op: prefix
                      value: /cart
                  - event_id: n3Q8kZvT2mRxW7cLpYbE4a
                    kind: event
                    label: Checkout
                  - kind: page
                    label: Thank you
                    page:
                      op: eq
                      value: /thank-you
                unit: session
              end_time: 1780358400000
              from_step: 1
              start_time: 1780272000000
            schema:
              $ref: '#/components/schemas/RumFunnelDriversRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  converted: 3184
                  factors:
                    - diff: -57.2
                      hit: 812
                      hit_rate: 21.4
                      issue_first_seen_version: 2.14.0
                      issue_status: unresolved
                      key: 01JQ7M2X4B9K3TD6V8WY5A1C0E
                      kind: error
                      label: >-
                        TypeError: Cannot read properties of undefined (reading
                        'total')
                      low_sample: false
                      miss: 2372
                      miss_rate: 78.6
                      sample_session: 0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81
                  flow:
                    - count: 912
                      from: ''
                      level: 1
                      to: /cart/shipping
                    - count: 631
                      from: ''
                      level: 1
                      to: ''
                  from_step: 1
                  next_pages:
                    - count: 912
                      page: /cart/shipping
                    - count: 631
                      page: ''
                  reached: 5120
                  sessions:
                    - duration_ms: 184000
                      factors:
                        - error
                        - slow_api
                      has_replay: true
                      session_id: 0a4a2e64-8a4f-4b9a-9c1e-3a2f9e6d7c81
                      views: 9
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - properties:
                      data:
                        $ref: '#/components/schemas/RumFunnelDrivers'
                    type: object
          description: 成功
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    RumFunnelDriversRequest:
      description: 解释漏斗中某一步到下一步之间的流失。
      properties:
        application_id:
          description: RUM 应用 ID。调用方需对该应用有读权限，写操作需要管理权限。
          type: string
        compare:
          description: >-
            在解释流失之前按该维度拆分漏斗，取
            `env`、`version`、`device_type`、`browser_name`、`os_name`、`geo_country`
            之一；省略则针对整体漏斗。
          enum:
            - env
            - version
            - device_type
            - browser_name
            - os_name
            - geo_country
          type: string
        definition:
          $ref: '#/components/schemas/RumFunnelDefinition'
          description: 漏斗定义：有序步骤、计数单位与可选过滤条件。允许 2-10 个步骤。
        end_time:
          description: 时间窗终点，Unix 毫秒时间戳。省略时取当前时间。
          example: 1780358400000
          format: int64
          type: integer
        from_step:
          description: 下钻的起始步骤，从 1 开始，必须是存在下一步的步骤。
          minimum: 1
          type: integer
        start_time:
          description: 时间窗起点，Unix 毫秒时间戳。两个边界都省略时取最近 7 天；超过 14 天的范围会被拒绝。
          example: 1780272000000
          format: int64
          type: integer
      required:
        - application_id
        - definition
        - from_step
      type: object
    SuccessEnvelope:
      description: >-
        成功响应结构。2xx 响应中 `request_id` 标识本次调用（同时出现在 `Flashcat-Request-Id`
        响应头中），`data` 为接口业务 payload。失败响应使用不同结构，参见 `ErrorResponse`。
      properties:
        data:
          description: 接口返回的数据，格式见各接口的 200 响应。没有返回数据的接口会返回 `{}` 或完全不带 `data`。
        request_id:
          description: 本次请求的唯一 ID，也会在 Flashcat-Request-Id 响应头中返回。反馈问题时请一并附上。
          example: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
          type: string
      required:
        - request_id
      type: object
    RumFunnelDrivers:
      description: 某一步到下一步之间的流失下钻结果。
      properties:
        converted:
          description: 继续进入下一步的计数单位数量。
          format: int64
          type: integer
        factors:
          description: 按区分转化与流失的能力排序的因素。
          items:
            $ref: '#/components/schemas/RumFunnelFactor'
          type: array
        flow:
          description: 流失单位的路径，以流向连线的形式给出。
          items:
            $ref: '#/components/schemas/RumFunnelFlowLink'
          type: array
        from_step:
          description: 下钻的起始步骤，从 1 开始。
          type: integer
        next_pages:
          description: 流失单位紧接着去了哪些页面。
          items:
            $ref: '#/components/schemas/RumFunnelNextPage'
          type: array
        reached:
          description: 到达该步骤的计数单位数量。
          format: int64
          type: integer
        sessions:
          description: 在此处流失的示例会话。
          items:
            $ref: '#/components/schemas/RumFunnelDroppedSession'
          type: array
      required:
        - from_step
        - reached
        - converted
        - factors
        - next_pages
        - flow
        - sessions
      type: object
    RumFunnelDefinition:
      description: 除名称外描述一个漏斗的全部内容。
      properties:
        filters:
          description: 计数前应用的过滤条件，省略表示不过滤。
          items:
            $ref: '#/components/schemas/RumFunnelFilter'
          type: array
        steps:
          description: 有序步骤，2-10 个。计数单位必须按此顺序依次到达才算转化。
          items:
            $ref: '#/components/schemas/RumFunnelStep'
          maxItems: 10
          minItems: 2
          type: array
        unit:
          description: 计数单位：`session` 按会话计数，`visitor` 按访客计数。
          enum:
            - session
            - visitor
          type: string
        window_hours:
          description: '`unit=visitor` 时的转化窗口，只能取 `24` 或 `168` 小时。按访客计数时必须提供，按会话计数时忽略。'
          enum:
            - 24
            - 168
          type: integer
      required:
        - steps
        - unit
      type: object
    RumFunnelFactor:
      description: 用于区分「转化」与「未转化」计数单位的因素。
      properties:
        diff:
          description: '`hit_rate` 减 `miss_rate`，单位为百分点；为负表示该因素降低转化。'
          type: number
        hit:
          description: 满足该因素的计数单位数量。
          format: int64
          type: integer
        hit_rate:
          description: 满足该因素的单位中完成转化的百分比。
          type: number
        issue_first_seen_version:
          description: '`error` 因素首次出现的版本；未知或其他类型时省略。'
          type: string
        issue_status:
          description: '`error` 因素对应的 Issue 状态，其他类型省略。'
          type: string
        key:
          description: >-
            因素标识：`error` 为 Issue ID，`slow_api` 为资源路径组。`slow_page`、`rage`、`dead`
            按整类统计，取值为空。
          type: string
        kind:
          description: >-
            因素类型：`error` 为归入 Issue 的错误，`slow_api` 为耗时超过 3 秒的
            XHR/fetch，`slow_page` 为 LCP 超过 4 秒的页面，`rage` 为暴怒点击，`dead` 为无效点击。
          enum:
            - error
            - slow_api
            - slow_page
            - rage
            - dead
          type: string
        label:
          description: >-
            便于阅读的标签：`error` 为错误类型与信息，`slow_api` 为资源路径组；`slow_page`、`rage`、`dead`
            为空。
          type: string
        low_sample:
          description: 任一侧的计数单位过少、不足以得出结论时为 `true`。
          type: boolean
        miss:
          description: 未满足该因素的计数单位数量。
          format: int64
          type: integer
        miss_rate:
          description: 未满足该因素的单位中完成转化的百分比。
          type: number
        sample_session:
          description: 满足该因素的示例会话 ID，可用于打开回放；没有时省略。
          type: string
      required:
        - kind
        - key
        - label
        - hit
        - hit_rate
        - miss
        - miss_rate
        - diff
      type: object
    RumFunnelFlowLink:
      description: 流失路径中相邻两层之间的一条连线。
      properties:
        count:
          description: 该连线上的计数单位数量。
          format: int64
          type: integer
        from:
          description: 上一层所在的页面路径组，第 1 跳为空。
          type: string
        level:
          description: 跳数。第 1 跳即离开该步骤，因此 `from` 为空。
          type: integer
        to:
          description: 本层所在的页面路径组。为单位离开站点时为空，为跳到本层前几名之外的页面时为 `*`。
          type: string
      required:
        - level
        - from
        - to
        - count
      type: object
    RumFunnelNextPage:
      description: 流失的计数单位在下一步去了哪里。
      properties:
        count:
          description: 前往该页面的计数单位数量。
          format: int64
          type: integer
        page:
          description: 它们接下来浏览的页面路径组；为空表示离开站点。
          type: string
      required:
        - page
        - count
      type: object
    RumFunnelDroppedSession:
      description: 未到达下一步的计数单位的一个示例会话。
      properties:
        duration_ms:
          description: 整个会话的时长（毫秒）。
          format: int64
          type: integer
        factors:
          description: 该会话在两步之间满足的因素类型。
          items:
            type: string
          type: array
        has_replay:
          description: 该会话是否有可打开的回放。
          type: boolean
        session_id:
          description: RUM 会话 ID。
          type: string
        views:
          description: 整个会话的页面浏览数。
          format: int64
          type: integer
      required:
        - session_id
        - has_replay
        - factors
        - duration_ms
        - views
      type: object
    ErrorResponse:
      description: 错误响应结构。`error` 必填，`data` 不存在。
      properties:
        error:
          $ref: '#/components/schemas/DutyError'
        request_id:
          description: 本次请求的唯一追踪 ID（trace ID），反馈问题时请提供该值以便检索日志。
          example: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
          type: string
      required:
        - request_id
        - error
      type: object
    RumFunnelFilter:
      description: 把漏斗限定在字段取值属于给定集合的事件上的一条过滤条件。
      properties:
        field:
          description: >-
            拆分维度：`env`、`version`、`device_type`、`browser_name`、`os_name`、`geo_country`，即
            views 与 actions 两张表共有的列。
          enum:
            - env
            - version
            - device_type
            - browser_name
            - os_name
            - geo_country
          type: string
        values:
          description: 该字段允许的取值，1-50 个。
          items:
            type: string
          maxItems: 50
          minItems: 1
          type: array
      required:
        - field
        - values
      type: object
    RumFunnelStep:
      description: 漏斗的一个步骤。
      properties:
        event_id:
          description: '`event` 步骤引用的行为事件 ID，其他类型忽略。'
          type: string
        kind:
          description: >-
            步骤类型：`page` 为按页面路径组匹配的页面浏览（需 `page`），`event` 为已保存的行为事件（需
            `event_id`），`custom` 为代码里通过 `addAction` 上报的动作（需 `name`）。
          enum:
            - page
            - event
            - custom
          type: string
        label:
          description: 步骤显示名，会原样出现在结果里的 `label`。默认空字符串。
          type: string
        name:
          description: '`custom` 步骤的动作名，需完全一致，其他类型忽略。'
          maxLength: 512
          type: string
        page:
          $ref: '#/components/schemas/RumBehaviorMatch'
          description: '`page` 步骤的页面匹配条件，其他类型忽略。'
      required:
        - kind
      type: object
    DutyError:
      description: 响应结构中的错误 payload，仅在非 2xx 响应时出现。
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          description: >-
            按响应语言（query 参数 `locale` / `lang` 或请求头
            `Accept-Language`）返回的错误描述，可能包含出错的字段名，请不要解析它。
          example: The specified parameter template_id is not valid.
      required:
        - code
        - message
      type: object
    RumBehaviorMatch:
      description: 针对页面路径组的一次比较。
      properties:
        op:
          description: >-
            `value` 与页面路径组的比较方式：`eq` 完全相等、`contains` 包含子串、`prefix`
            前缀匹配、`wildcard` 锚定的 `*` 通配、`regex` 正则匹配。
          enum:
            - eq
            - contains
            - prefix
            - wildcard
            - regex
          type: string
        value:
          description: 比较值。最多 512 字节且不能含控制字符；`regex` 取值限制 200 字节且必须能编译。
          maxLength: 512
          type: string
      required:
        - op
        - value
      type: object
    ErrorCode:
      description: >-
        错误码。所有失败响应都会把 `error.code` 设为下列稳定字符串之一，请以它而不是 HTTP 状态码做判断。


        | 错误码 | HTTP | 含义 |

        |---|---|---|

        | `OK` | 200 | 保留值，失败的请求不会返回。 |

        | `InvalidParameter` | 400 | 参数缺失、类型错误或未通过校验，`message` 通常会指出字段名。 |

        | `BadRequest` | 400 | 请求违反业务规则或与对象当前状态冲突，`message` 会说明原因。 |

        | `InvalidContentType` | 400 | 请求体没有以 `application/json` 发送。 |

        | `ResourceNotFound` | 400 | 引用的对象在本账户中不存在或已删除。注意 HTTP 状态码是 400 而不是 404。
        |

        | `NoLicense` | 400 | 账户套餐不包含该功能、套餐配额已用完、套餐已过期或额度不足。 |

        | `ReferenceExist` | 400 | 对象仍被其他对象引用，无法删除。 |

        | `Unauthorized` | 401 | APP Key 缺失、无效或已删除。 |

        | `BalanceNotEnough` | 402 | 仅用于控制台计费流程，Open API 接口不会返回。 |

        | `AccessDenied` | 403 | APP Key 的权限范围或创建者角色不允许该操作或该对象。 |

        | `RouteNotFound` | 404 | 没有与该 HTTP 方法和路径匹配的接口。 |

        | `MethodNotAllowed` | 405 | 路径存在，但不支持该 HTTP 方法。 |

        | `UndonedOrderExist` | 409 | 仅用于控制台计费流程，Open API 接口不会返回。 |

        | `EntityTooLarge` | 413 | 请求体超出大小限制。 |

        | `RequestLocked` | 423 | 仅用于控制台登录保护，Open API 接口不会返回。 |

        | `RequestVerifyRequired` | 428 | 仅用于控制台验证码流程，Open API 接口不会返回。 |

        | `DangerousOperation` | 428 | 仅用于控制台高风险操作的 MFA 校验，Open API 接口不会返回。 |

        | `RequestTooFrequently` | 429 | 触发频率限制；请等待响应头
        `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后再重试。 |

        | `InternalError` | 500 | 服务端意外错误；请退避后重试，反馈问题时附上 `request_id`。 |

        | `ServiceUnavailable` | 503 | 后端依赖过载或不可用，请退避后重试。 |
      enum:
        - OK
        - InvalidParameter
        - BadRequest
        - InvalidContentType
        - ResourceNotFound
        - NoLicense
        - ReferenceExist
        - Unauthorized
        - BalanceNotEnough
        - AccessDenied
        - RouteNotFound
        - MethodNotAllowed
        - UndonedOrderExist
        - EntityTooLarge
        - RequestLocked
        - RequestVerifyRequired
        - DangerousOperation
        - RequestTooFrequently
        - InternalError
        - ServiceUnavailable
      example: InvalidParameter
      type: string
      x-enumDescriptions:
        OK: 保留值，失败的请求不会返回。
        InvalidParameter: 参数缺失、类型错误或未通过校验，`message` 通常会指出字段名。
        BadRequest: 请求违反业务规则或与对象当前状态冲突，`message` 会说明原因。
        InvalidContentType: 请求体没有以 `application/json` 发送。
        ResourceNotFound: 引用的对象在本账户中不存在或已删除。注意 HTTP 状态码是 400 而不是 404。
        NoLicense: 账户套餐不包含该功能、套餐配额已用完、套餐已过期或额度不足。
        ReferenceExist: 对象仍被其他对象引用，无法删除。
        Unauthorized: APP Key 缺失、无效或已删除。
        BalanceNotEnough: 仅用于控制台计费流程，Open API 接口不会返回。
        AccessDenied: APP Key 的权限范围或创建者角色不允许该操作或该对象。
        RouteNotFound: 没有与该 HTTP 方法和路径匹配的接口。
        MethodNotAllowed: 路径存在，但不支持该 HTTP 方法。
        UndonedOrderExist: 仅用于控制台计费流程，Open API 接口不会返回。
        EntityTooLarge: 请求体超出大小限制。
        RequestLocked: 仅用于控制台登录保护，Open API 接口不会返回。
        RequestVerifyRequired: 仅用于控制台验证码流程，Open API 接口不会返回。
        DangerousOperation: 仅用于控制台高风险操作的 MFA 校验，Open API 接口不会返回。
        RequestTooFrequently: 触发频率限制；请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后再重试。
        InternalError: 服务端意外错误；请退避后重试，反馈问题时附上 `request_id`。
        ServiceUnavailable: 后端依赖过载或不可用，请退避后重试。
  responses:
    BadRequest:
      content:
        application/json:
          examples:
            missingParameter:
              value:
                error:
                  code: InvalidParameter
                  message: The specified parameter is not valid.
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: 请求非法 — 通常是参数缺失或格式不正确。
    Unauthorized:
      content:
        application/json:
          examples:
            missingAppKey:
              value:
                error:
                  code: Unauthorized
                  message: You are unauthorized.
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: app_key 缺失或无效。
    Forbidden:
      content:
        application/json:
          examples:
            noEditPermission:
              value:
                error:
                  code: AccessDenied
                  message: Access Denied.
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: app_key 有效，但其权限范围或创建者角色不允许该操作或该对象。
    TooManyRequests:
      content:
        application/json:
          examples:
            rateLimited:
              value:
                error:
                  code: RequestTooFrequently
                  message: Request too frequently.
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: 触发频率限制。请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后重试。
      headers:
        Flashcat-Request-Rate-Limit-Delay:
          description: 距当前限流窗口重置的秒数。请求被网关全局保护限流拒绝时不返回该响应头。
          schema:
            type: integer
            minimum: 0
    ServerError:
      content:
        application/json:
          examples:
            internal:
              value:
                error:
                  code: InternalError
                  message: >-
                    We encountered an internal error, and it has been reported.
                    Please try again later.
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: 服务端未预期错误。反馈问题时请携带 request_id。
  securitySchemes:
    AppKeyAuth:
      description: >-
        在 Flashduty 控制台 我的 → APP Key 中创建的 APP Key。可通过 query 参数 `app_key` 或请求头
        `Fd-App-Key` 传入。实际可访问范围是该 APP Key 的权限范围与创建者当前角色权限的交集，请妥善保管。
      in: query
      name: app_key
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.