> ## 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.

# Explain a step's drop-off

> Explain why units dropped between one funnel step and the next: factors, next pages, paths and example sessions.

## Restrictions

| Aspect | Value |
| - | - |
| Rate limits | **200 requests/minute**; **10 requests/second** per account |
| Permissions | None — any valid `app_key` can call this operation |

## Usage

* `start_time` and `end_time` are Unix epoch milliseconds. Omit both to use the last 7 days; a range wider than 14 days returns `InvalidParameter`.
* The caller needs read access to `application_id`; data of private applications the caller cannot access is not counted.
* `from_step` is 1-based and must have a following step.
* Factors are ranked by how much they separate converted from dropped units; `low_sample=true` marks a factor with too few units to be conclusive.
* In `flow`, an empty `to` means the units left the site and `*` means they went to pages outside that hop's top few.


## OpenAPI

````yaml /api-reference/rum.openapi.en.json post /rum/funnel/drivers
openapi: 3.1.0
info:
  description: >-
    Public HTTP API for the Flashduty incident management platform — incidents,
    notification templates, channels, schedules, monitors, RUM, and platform
    administration. Every operation is authenticated with an `app_key` query
    parameter created in the Flashduty console under My → APP Key (or sent in
    the `Fd-App-Key` header). Responses follow a uniform envelope: `{
    request_id, data }` on success, `{ request_id, error }` on failure.
  title: Flashduty Open API
  version: 1.0.0
servers:
  - description: Flashduty Open API
    url: https://api.flashcat.cloud
security:
  - AppKeyAuth: []
tags:
  - description: Manage Real User Monitoring (RUM) applications.
    name: RUM/Applications
  - description: Run RUM analytics queries over event data.
    name: RUM/Data query
  - description: Query and manage RUM error tracking issues and preset severity rules.
    name: RUM/Issues
  - description: >-
      Query RUM facet fields and their value distributions for building
      analytics filters.
    name: RUM/Facets
  - description: >-
      Manage and query RUM sourcemap files for browser, Android, and iOS error
      symbolication.
    name: RUM/Sourcemaps
  - description: Retrieve session replay metadata and recorded segments for RUM sessions.
    name: RUM/Session replay
  - description: >-
      Configure and inspect the rules that decide which RUM errors get ingested
      and stored for an application, including their edit history.
    name: RUM/Error ingestion rules
  - description: >-
      Manage per-application rules that assign a severity to matching front-end
      errors, plus their evaluation order and change history.
    name: RUM/Issue preset severity rules
  - description: Query the RUM resource record and current usage for the account.
    name: RUM/Resources
  - description: >-
      Create and manage RUM custom dashboards, their revision history and the
      trash.
    name: RUM/Dashboards
  - description: >-
      Define and inspect the behavior events that saved rules turn raw RUM
      actions into.
    name: RUM/Behavior events
  - description: >-
      Analyse conversion funnels over RUM sessions and visitors: results,
      trends, breakdowns, drop-off drivers and page flows.
    name: RUM/Funnels
  - description: >-
      Read page heatmaps: element ranking, click points, scroll depth and the
      replay frame used as background.
    name: RUM/Heatmaps
paths:
  /rum/funnel/drivers:
    post:
      tags:
        - RUM/Funnels
      summary: Explain a step's drop-off
      description: >-
        Explain why units dropped between one funnel step and the next: factors,
        next pages, paths and example sessions.
      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: Success
        '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: Explain the drop between one funnel step and the next.
      properties:
        application_id:
          description: >-
            RUM application ID. The caller needs read access to it; for write
            operations, manage access.
          type: string
        compare:
          description: >-
            Split the funnel by this dimension before explaining the drop:
            `env`, `version`, `device_type`, `browser_name`, `os_name` or
            `geo_country`. Omit for the overall funnel.
          enum:
            - env
            - version
            - device_type
            - browser_name
            - os_name
            - geo_country
          type: string
        definition:
          $ref: '#/components/schemas/RumFunnelDefinition'
          description: >-
            Funnel definition: the ordered steps, the counting unit and optional
            filters. 2 to 10 steps.
        end_time:
          description: >-
            End of the window, Unix timestamp in milliseconds. Defaults to now
            when omitted.
          example: 1780358400000
          format: int64
          type: integer
        from_step:
          description: >-
            Step the drill-down starts from, 1-based. It must be a step with a
            following one.
          minimum: 1
          type: integer
        start_time:
          description: >-
            Start of the window, Unix timestamp in milliseconds. Omit both
            bounds to use the last 7 days; a range wider than 14 days is
            rejected.
          example: 1780272000000
          format: int64
          type: integer
      required:
        - application_id
        - definition
        - from_step
      type: object
    SuccessEnvelope:
      description: >-
        Success response envelope. On every 2xx response, `request_id`
        identifies the call (also mirrored in the `Flashcat-Request-Id` header)
        and `data` holds the endpoint-specific payload. Failure responses use a
        different shape — see `ErrorResponse`.
      properties:
        data:
          description: >-
            Operation-specific payload, documented in each operation's 200
            response. Operations without a payload return `{}` or omit `data`
            entirely.
        request_id:
          description: >-
            Unique ID for this request. Mirrored in the Flashcat-Request-Id
            response header. Include it when reporting issues.
          example: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
          type: string
      required:
        - request_id
      type: object
    RumFunnelDrivers:
      description: Drill-down for the transition from one step to the next.
      properties:
        converted:
          description: Units that went on to the next step.
          format: int64
          type: integer
        factors:
          description: >-
            Factors ranked by how much they separate converted from dropped
            units.
          items:
            $ref: '#/components/schemas/RumFunnelFactor'
          type: array
        flow:
          description: The dropped units' paths as flow links.
          items:
            $ref: '#/components/schemas/RumFunnelFlowLink'
          type: array
        from_step:
          description: Step the drill-down starts from, 1-based.
          type: integer
        next_pages:
          description: Where the dropped units went right after the step.
          items:
            $ref: '#/components/schemas/RumFunnelNextPage'
          type: array
        reached:
          description: Units that reached that step.
          format: int64
          type: integer
        sessions:
          description: Example sessions that dropped here.
          items:
            $ref: '#/components/schemas/RumFunnelDroppedSession'
          type: array
      required:
        - from_step
        - reached
        - converted
        - factors
        - next_pages
        - flow
        - sessions
      type: object
    RumFunnelDefinition:
      description: Everything that describes a funnel except its name.
      properties:
        filters:
          description: Filters applied before counting. Omit for no filtering.
          items:
            $ref: '#/components/schemas/RumFunnelFilter'
          type: array
        steps:
          description: >-
            Ordered steps. 2-10 steps; units must reach them in this order to
            convert.
          items:
            $ref: '#/components/schemas/RumFunnelStep'
          maxItems: 10
          minItems: 2
          type: array
        unit:
          description: 'Counting unit: `session` counts sessions, `visitor` counts visitors.'
          enum:
            - session
            - visitor
          type: string
        window_hours:
          description: >-
            Conversion window for `unit=visitor`: `24` or `168` hours. Must be
            set for visitors and is ignored for sessions.
          enum:
            - 24
            - 168
          type: integer
      required:
        - steps
        - unit
      type: object
    RumFunnelFactor:
      description: >-
        A factor that separates units which converted from the step from those
        that did not.
      properties:
        diff:
          description: >-
            `hit_rate` minus `miss_rate`, in percentage points; negative means
            the factor hurts conversion.
          type: number
        hit:
          description: Units that met the factor.
          format: int64
          type: integer
        hit_rate:
          description: Percentage of the units that met it and then converted.
          type: number
        issue_first_seen_version:
          description: >-
            Version an `error` factor was first seen in. Omitted when unknown or
            for other kinds.
          type: string
        issue_status:
          description: Issue status for an `error` factor. Omitted for other kinds.
          type: string
        key:
          description: >-
            Factor identity: the issue ID for `error`, the resource path group
            for `slow_api`. Empty for `slow_page`, `rage` and `dead`, which are
            counted as whole kinds.
          type: string
        kind:
          description: >-
            Factor kind: `error` an error grouped into an issue, `slow_api` an
            XHR/fetch slower than 3 s, `slow_page` a page whose LCP exceeded 4
            s, `rage` a rage click or tap, `dead` a dead click.
          enum:
            - error
            - slow_api
            - slow_page
            - rage
            - dead
          type: string
        label:
          description: >-
            Human-readable label: the error type and message for `error`, the
            resource path group for `slow_api`; empty for `slow_page`, `rage`
            and `dead`.
          type: string
        low_sample:
          description: >-
            `true` when either side has too few units for the comparison to be
            conclusive.
          type: boolean
        miss:
          description: Units that did not meet the factor.
          format: int64
          type: integer
        miss_rate:
          description: Percentage of the units that did not meet it and still converted.
          type: number
        sample_session:
          description: >-
            A session that met the factor, to open in replay. Omitted when none
            is available.
          type: string
      required:
        - kind
        - key
        - label
        - hit
        - hit_rate
        - miss
        - miss_rate
        - diff
      type: object
    RumFunnelFlowLink:
      description: One band of the flow of dropped units between two hops.
      properties:
        count:
          description: Units on this link.
          format: int64
          type: integer
        from:
          description: Page path group at the previous hop. Empty at hop 1.
          type: string
        level:
          description: Hop number; hop 1 leaves the step itself, so its `from` is empty.
          type: integer
        to:
          description: >-
            Page path group at this hop. Empty when the units left the site, `*`
            when they went to pages outside this hop's top few.
          type: string
      required:
        - level
        - from
        - to
        - count
      type: object
    RumFunnelNextPage:
      description: Where dropped units went right after the step.
      properties:
        count:
          description: Units that went there.
          format: int64
          type: integer
        page:
          description: Page path group they viewed next. Empty means they left.
          type: string
      required:
        - page
        - count
      type: object
    RumFunnelDroppedSession:
      description: An example session of a unit that did not reach the next step.
      properties:
        duration_ms:
          description: Duration of the whole session, in milliseconds.
          format: int64
          type: integer
        factors:
          description: Factor kinds the session met between the two steps.
          items:
            type: string
          type: array
        has_replay:
          description: Whether the session has a replay to open.
          type: boolean
        session_id:
          description: RUM session ID.
          type: string
        views:
          description: Views in the whole session.
          format: int64
          type: integer
      required:
        - session_id
        - has_replay
        - factors
        - duration_ms
        - views
      type: object
    ErrorResponse:
      description: Response envelope for errors. `error` is required; `data` is absent.
      properties:
        error:
          $ref: '#/components/schemas/DutyError'
        request_id:
          description: >-
            Unique trace ID of this request; include it when reporting issues so
            logs can be located.
          example: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
          type: string
      required:
        - request_id
        - error
      type: object
    RumFunnelFilter:
      description: >-
        One filter narrowing the funnel to events whose field holds one of the
        values.
      properties:
        field:
          description: >-
            Dimension to split by: `env`, `version`, `device_type`,
            `browser_name`, `os_name` or `geo_country` — the columns shared by
            the views and actions tables.
          enum:
            - env
            - version
            - device_type
            - browser_name
            - os_name
            - geo_country
          type: string
        values:
          description: Accepted values for the field. 1-50 values.
          items:
            type: string
          maxItems: 50
          minItems: 1
          type: array
      required:
        - field
        - values
      type: object
    RumFunnelStep:
      description: One step of a funnel.
      properties:
        event_id:
          description: Behavior event of an `event` step. Ignored for other kinds.
          type: string
        kind:
          description: >-
            Step kind: `page` is a page view matched on the page path group
            (needs `page`), `event` is a saved behavior event (needs
            `event_id`), `custom` is an action reported in code through
            `addAction` (needs `name`).
          enum:
            - page
            - event
            - custom
          type: string
        label:
          description: >-
            Label shown for the step; it is echoed back as the step result's
            `label`. Defaults to an empty string.
          type: string
        name:
          description: >-
            Action name of a `custom` step, matched exactly. Ignored for other
            kinds.
          maxLength: 512
          type: string
        page:
          $ref: '#/components/schemas/RumBehaviorMatch'
          description: Page match of a `page` step. Ignored for other kinds.
      required:
        - kind
      type: object
    DutyError:
      description: >-
        Error payload inside the response envelope. Present only on non-2xx
        responses.
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          description: >-
            Human-readable error message in the response language (`locale` /
            `lang` query parameter or `Accept-Language` header). May name the
            offending field; do not parse it.
          example: The specified parameter template_id is not valid.
      required:
        - code
        - message
      type: object
    RumBehaviorMatch:
      description: One comparison against the page path group.
      properties:
        op:
          description: >-
            How `value` is compared with the page path group: `eq` exactly,
            `contains` a substring, `prefix` from the start, `wildcard` an
            anchored `*` glob, `regex` a regular expression.
          enum:
            - eq
            - contains
            - prefix
            - wildcard
            - regex
          type: string
        value:
          description: >-
            Comparison value. At most 512 bytes without control characters; a
            `regex` value is limited to 200 bytes and must compile.
          maxLength: 512
          type: string
      required:
        - op
        - value
      type: object
    ErrorCode:
      description: >-
        Error code. Every failed response sets `error.code` to one of these
        stable strings; branch on it rather than on the HTTP status.


        | Code | HTTP | Meaning |

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

        | `OK` | 200 | Reserved; never returned on a failed request. |

        | `InvalidParameter` | 400 | A parameter is missing, has the wrong type,
        or failed validation; `message` usually names the field. |

        | `BadRequest` | 400 | The request breaks a business rule or conflicts
        with the current state of an object; `message` says which. |

        | `InvalidContentType` | 400 | The body is not sent as
        `application/json`. |

        | `ResourceNotFound` | 400 | The referenced object does not exist in
        this account or was deleted. Returned as HTTP 400, not 404. |

        | `NoLicense` | 400 | The account's plan does not include the feature, a
        plan quota is used up, the plan has expired, or credits are
        insufficient. |

        | `ReferenceExist` | 400 | The object is still referenced by other
        objects, so it cannot be deleted. |

        | `Unauthorized` | 401 | The APP Key is missing, invalid, or deleted. |

        | `BalanceNotEnough` | 402 | Console-only (billing); not returned by
        Open API operations. |

        | `AccessDenied` | 403 | The APP Key's permission scope or the creator's
        role does not allow this operation or object. |

        | `RouteNotFound` | 404 | No operation matches the HTTP method and path.
        |

        | `MethodNotAllowed` | 405 | The path exists but not for this HTTP
        method. |

        | `UndonedOrderExist` | 409 | Console-only (billing); not returned by
        Open API operations. |

        | `EntityTooLarge` | 413 | The request body exceeds the size limit. |

        | `RequestLocked` | 423 | Console-only (sign-in protection); not
        returned by Open API operations. |

        | `RequestVerifyRequired` | 428 | Console-only (verification code); not
        returned by Open API operations. |

        | `DangerousOperation` | 428 | Console-only (MFA for high-risk actions);
        not returned by Open API operations. |

        | `RequestTooFrequently` | 429 | A rate limit was hit; wait for the
        `Flashcat-Request-Rate-Limit-Delay` response header (seconds) before
        retrying. |

        | `InternalError` | 500 | Unexpected server error; retry with backoff
        and include `request_id` when reporting. |

        | `ServiceUnavailable` | 503 | A backend dependency is overloaded or
        unavailable; retry with backoff. |
      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: Reserved; never returned on a failed request.
        InvalidParameter: >-
          A parameter is missing, has the wrong type, or failed validation;
          `message` usually names the field.
        BadRequest: >-
          The request breaks a business rule or conflicts with the current state
          of an object; `message` says which.
        InvalidContentType: The body is not sent as `application/json`.
        ResourceNotFound: >-
          The referenced object does not exist in this account or was deleted.
          Returned as HTTP 400, not 404.
        NoLicense: >-
          The account's plan does not include the feature, a plan quota is used
          up, the plan has expired, or credits are insufficient.
        ReferenceExist: >-
          The object is still referenced by other objects, so it cannot be
          deleted.
        Unauthorized: The APP Key is missing, invalid, or deleted.
        BalanceNotEnough: Console-only (billing); not returned by Open API operations.
        AccessDenied: >-
          The APP Key's permission scope or the creator's role does not allow
          this operation or object.
        RouteNotFound: No operation matches the HTTP method and path.
        MethodNotAllowed: The path exists but not for this HTTP method.
        UndonedOrderExist: Console-only (billing); not returned by Open API operations.
        EntityTooLarge: The request body exceeds the size limit.
        RequestLocked: >-
          Console-only (sign-in protection); not returned by Open API
          operations.
        RequestVerifyRequired: Console-only (verification code); not returned by Open API operations.
        DangerousOperation: >-
          Console-only (MFA for high-risk actions); not returned by Open API
          operations.
        RequestTooFrequently: >-
          A rate limit was hit; wait for the `Flashcat-Request-Rate-Limit-Delay`
          response header (seconds) before retrying.
        InternalError: >-
          Unexpected server error; retry with backoff and include `request_id`
          when reporting.
        ServiceUnavailable: A backend dependency is overloaded or unavailable; retry with backoff.
  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: Invalid request — usually a missing or malformed parameter.
    Unauthorized:
      content:
        application/json:
          examples:
            missingAppKey:
              value:
                error:
                  code: Unauthorized
                  message: You are unauthorized.
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Missing or invalid app_key.
    Forbidden:
      content:
        application/json:
          examples:
            noEditPermission:
              value:
                error:
                  code: AccessDenied
                  message: Access Denied.
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: >-
        The app_key is valid, but its permission scope or the creator's role
        does not allow this operation or object.
    TooManyRequests:
      content:
        application/json:
          examples:
            rateLimited:
              value:
                error:
                  code: RequestTooFrequently
                  message: Request too frequently.
                request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: >-
        Rate limit hit. Wait for the number of seconds in
        `Flashcat-Request-Rate-Limit-Delay`, then retry.
      headers:
        Flashcat-Request-Rate-Limit-Delay:
          description: >-
            Seconds until the current rate-limit window resets. Absent when the
            request was rejected by the gateway's global protection limit.
          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: Unexpected server-side error. Include the request_id when reporting.
  securitySchemes:
    AppKeyAuth:
      description: >-
        APP Key created in the Flashduty console under My → APP Key. Send it as
        the `app_key` query parameter or in the `Fd-App-Key` request header. Its
        effective access is the intersection of the key's permission scope and
        the creator's current role permissions. Keep it secret.
      in: query
      name: app_key
      type: apiKey

````

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