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.

For users of other query languages

If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL.

Splunk SPL users

In Splunk SPL, you would typically use eval with mvcount to count array elements, but there’s no built-in function specifically for counting conversation turns.

Splunk example

| eval turn_count=mvcount(messages)/2

ANSI SQL users

In ANSI SQL, you would need to unnest the array and count rows, then divide by the number of roles, which is more complex.

SQL example

SELECT 
  conversation_id,
  COUNT(*) / 2 as turn_count
FROM conversations
CROSS JOIN UNNEST(messages)
GROUP BY conversation_id

Usage

Syntax

genai_conversation_turns(messages)

Parameters

• messages (dynamic, required): 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.

Use case examples

Log analysis

Track conversation length across different API endpoints to understand user engagement and conversation complexity.

Query

['sample-http-logs']
| where uri contains '/api/chat'
| extend turns = genai_conversation_turns(todynamic(response_body)['messages'])
| summarize avg_turns = avg(turns), max_turns = max(turns) by uri

Run in Playground

Output

uri	avg_turns	max_turns
/api/chat/support	3.5	12
/api/chat/sales	2.1	8

This query calculates the average and maximum number of conversation turns for different chat endpoints, helping you understand which services have longer conversations.

List of related functions

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