# `Journey.Insights.FlowAnalytics`
[🔗](https://github.com/shipworthy/journey/blob/main/lib/journey/insights/flow_analytics.ex#L1)

Provides system-wide aggregate data about the state of the executions of a particular graph.
This can be thought of as "analytics" for a particular graph.

# `flow_analytics`

Provides business-focused analytics for understanding customer behavior through Journey graphs.

Uses optimized database queries that scale efficiently to millions of executions by leveraging
PostgreSQL's aggregation capabilities. System nodes (execution_id and last_updated_at) are
automatically excluded from the analysis.

## Parameters

- `graph_name` - String, the graph name to analyze
- `graph_version` - String, the graph version to analyze
- `opts` - Keyword list with options:
  - `:include_executions` - `:all` | `:archived` | `:active` (default: `:active`)
  - `:flow_ends_here_after` - Duration in seconds after which we consider a flow "ended" if no activity (default: 86400 seconds / 1 day)

## Return Structure

Returns a map with graph metadata, execution-level analytics, and per-node customer journey metrics.

## Examples

  iex(3)> Journey.Insights.FlowAnalytics.flow_analytics("Credit Card Application flow graph", "v1.0.0")
  %{
    graph_name: "Credit Card Application flow graph",
    analyzed_at: "2025-08-02T04:08:28.351195Z",
    executions: %{
      count: 8294,
      duration_avg_seconds_to_last_update: 48,
      duration_median_seconds_to_last_update: 0
    },
    graph_version: "v1.0.0",
    node_stats: %{
      nodes: [
        %{
          node_type: :input,
          node_name: :birth_date,
          # The number of executions that have set a value for this node.
          reached_count: 3884,
          # The average time it took for an execution to reach this node.
          average_time_to_reach: 1,
          # The number of executions which haven't been updated for a while, and this was the last node that was updated.
          flow_ends_here_count: 1953,
          # The percentage of all executions that ended here.
          flow_ends_here_percentage_of_all: 23.5,
          # The percentage of executions that reached this node and ended here.
          flow_ends_here_percentage_of_reached: 50.28,
          # The percentage of executions that have set a value for this node.
          reached_percentage: 46.8
        },
        %{
          node_type: :input,
          node_name: :email_address,
          reached_count: 2066,
          average_time_to_reach: 0,
          flow_ends_here_count: 213,
          flow_ends_here_percentage_of_all: 2.6,
          flow_ends_here_percentage_of_reached: 10.31,
          reached_percentage: 24.9
        },
        %{
          node_type: :input,
          node_name: :full_name,
          reached_count: 5736,
          average_time_to_reach: 0,
          flow_ends_here_count: 3716,
          flow_ends_here_percentage_of_all: 44.8,
          flow_ends_here_percentage_of_reached: 64.78,
          reached_percentage: 69.2
        },
        %{
          node_type: :compute,
          node_name: :credit_score,
          reached_count: 1844,
          average_time_to_reach: 1,
          flow_ends_here_count: 0,
          flow_ends_here_percentage_of_all: 0.0,
          flow_ends_here_percentage_of_reached: 0.0,
          reached_percentage: 22.2
        },
        ...
      ]
    }
  }

# `to_text`

Formats flow analytics data as human-readable text output.

## Example:

    iex> flow_data = Journey.Insights.FlowAnalytics.flow_analytics("Credit Card Application flow graph", "v1.0.0")
    iex> Journey.Insights.FlowAnalytics.to_text(flow_data) |> IO.puts()
    Graph: 'Credit Card Application flow graph'
    Version: 'v1.0.0'
    Analyzed at: 2025-08-02T04:08:28Z

    EXECUTION STATS:
    ----------
    Total executions: 8,294
    Average duration: 48 seconds
    Median duration: 0 seconds

    NODE STATS (4 nodes):
    ----------
    Node Name: 'birth_date'
    Type: input
    Reached by: 3,884 executions (46.8%)
    Average time to reach: 1 second
    Flow ends here: 1,953 executions (23.5% of all, 50.3% of reached)

    Node Name: 'email_address'
    Type: input
    Reached by: 2,066 executions (24.9%)
    Average time to reach: 0 seconds
    Flow ends here: 213 executions (2.6% of all, 10.3% of reached)

    Node Name: 'full_name'
    Type: input
    Reached by: 5,736 executions (69.2%)
    Average time to reach: 0 seconds
    Flow ends here: 3,716 executions (44.8% of all, 64.8% of reached)

    Node Name: 'credit_score'
    Type: compute
    Reached by: 1,844 executions (22.2%)
    Average time to reach: 1 second
    Flow ends here: 0 executions (0.0% of all, 0.0% of reached)

---

*Consult [api-reference.md](api-reference.md) for complete listing*