genai_conversation_turns

This page explains how to use the genai_conversation_turns function in APL.

The genai_conversation_turns function counts the number of conversation turns in a GenAI messages array. A turn typically represents a user message followed by an assistant response. This metric helps you understand conversation length and engagement patterns in AI applications.

You can use this function to analyze conversation complexity, monitor user engagement, identify outlier conversations, or track conversation metrics for billing and usage analysis.

Usage

Syntax

APL

genai_conversation_turns(messages)

Parameters

Name	Type	Required	Description
messages	dynamic	Yes	An array of message objects from a GenAI conversation. Each message typically contains a `role` and `content` field.

Returns

Returns a long integer representing the number of conversation turns. A turn is typically counted as a user-assistant exchange pair.

Example

Count the number of conversation turns in a GenAI chat operation.

Query

APLRun in Playground

['otel-demo-genai']
| extend turns = genai_conversation_turns(['attributes.gen_ai.input.messages'])
| summarize avg_turns = avg(turns), max_turns = max(turns)

Output

avg_turns	max_turns
4.2	12

This query calculates the average and maximum number of conversation turns, helping you understand conversation complexity and engagement patterns.

genai_message_roles: Extracts all message roles to understand conversation structure. Use this when you need to analyze the role distribution in conversations.
array_length: Returns the total number of messages (not turns). Use this when you need the raw message count instead of turn count.
genai_cost: Calculates the cost of a conversation. Use this in combination with turn count to understand cost per turn.
genai_estimate_tokens: Estimates token usage. Use this with turn count to analyze tokens per turn.