Call history data model: segments and nodes
The Zoom Phone API enables developers to access and analyze detailed telephony data, including call history, recordings, and SMS.
Each call in the Call History API is represented using segments (sequential steps) and nodes (parallel branches), which together allow reconstruction of complex call flows, such as transfers, queues, and multi-agent rings.
Understanding these identifiers is key to interpreting call data accurately and building reliable analytics or integrations.
-
Segment — Represents the sequential stage of the call
-
Node — Represents parallel branches or attempts within a given segment
Understanding segments
A segment identifies a logical step or leg in the progression of a call. Segments always start at 1 for the initial call and they increment when the call transitions to a new logical leg, including:
- Direct or blind transfers
- Queue transfers or escalations
- Device/endpoint changes
- Auto receptionist or IVR steps
NOTE: All call elements with the same segment value belong to the same logical step of the call.
Understanding nodes
A node identifies an individual attempt, branch, or participant path within a specific segment.
| Node Value | Meaning |
|---|---|
| node = 1 | Primary or successful branch (e.g., answered leg, winning agent) |
| node = 0 | Secondary or unsuccessful branches (e.g., unanswered attempts, fan-out targets) |
Multiple nodes may exist within the same segment, representing simultaneous or parallel call attempts:
segment 3:
node 1 → agent who answered
node 0 → agents who did not answer
Interpreting call flows
A complete call flow can be reconstructed using this hierarchy: segment → node → events
Segment defines when in the call the events occurred. Node defines which parallel path within that segment the events belong to.
Example call flow model
Segment 1 (initial inbound)
Node 1 — queue or user receives the call
Segment 2 (transfer operation)
Node 1 — transfer initiator
Node 0 — secondary system events
Segment 3 (new queue/ring group)
Node 1 — agent who answered
Node 0 — agents who were attempted but did not answer
Known patterns
| Condition | Behavior |
|---|---|
| Initial segment | Always segment = 1, node = 1 |
| Multi-agent ring | Multiple nodes (0 + 1) in same segment |
| Transfers | Always introduce a new segment |
| Queue routing | Often creates a new segment with multiple nodes |
| Agent who answered | Typically appears as node = 1 |
Implementation guidance for developers
1. Grouping:
Developers should group call elements using:
call_id, segment, node
2. Flow reconstruction:
- Order by segment (ascending) to follow the call timeline
- Within each segment, prioritize node = 1 events as the primary path
- Use additional fields (result, action, direction) to determine the outcome of each branch
3. Special scenarios:
In queue/ring group scenarios
- Expect multiple node = 0 entries for simultaneous ring attempts
- node = 1 identifies the agent who answered
- All nodes share the same segment value
Transfer scenarios:
- Any transfer (blind or attended) produces a new segment
- Multiple nodes may appear in the transfer segment due to intermediate system events.
Summary
- Segments represent sequential call legs (starting at 1)
- Nodes represent parallel attempts within a segment
- Node 1 typically indicates the successful/primary path
- Node 0 represents secondary paths or system events
- The call summary record appears as node 0, segment 1
This model enables complete reconstruction of complex call flows, including multi-party scenarios, transfers, and parallel ring attempts.