Skip to main content
The genai_get_content_by_role function retrieves the content of a message with a specific role from a GenAI messages array. It returns the first message matching the specified role (such as ‘user’, ‘assistant’, ‘system’, or ‘tool’). You can use this function to extract messages by role, filter conversations by participant type, analyze specific role patterns, or process messages from particular conversation participants.

​
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.
In Splunk SPL, you would use mvfilter to filter by role and then extract the content.
| eval filtered_msgs=mvfilter(match(role, "system"))
| eval content=mvindex(filtered_msgs, 0)
In ANSI SQL, you would unnest the array, filter by role, and limit to the first result.
SELECT 
  conversation_id,
  content
FROM conversations
CROSS JOIN UNNEST(messages)
WHERE role = 'system'
LIMIT 1

​
Usage

​
Syntax

genai_get_content_by_role(messages, role)

​
Parameters

NameTypeRequiredDescription
messagesdynamicYesAn array of message objects from a GenAI conversation. Each message typically contains role and content fields.
rolestringYesThe role to filter by. Common values include ‘user’, ‘assistant’, ‘system’, ‘tool’, or ‘function’.

​
Returns

Returns a string containing the content of the first message with the specified role, or an empty string if no matching message is found.

​
Example

Extract the content of the system message from a GenAI conversation. Query 
['genai-traces']
| extend system_content = genai_get_content_by_role(['attributes.gen_ai.input.messages'], 'system')
| where isnotempty(system_content)
| summarize conversation_count = count() by system_content
| top 3 by conversation_count
Output
system_contentconversation_count
You are a helpful shopping assistant.1250
You are a technical support expert.845
This query shows the distribution of system prompts being used, helping ensure configuration consistency.
  • genai_get_content_by_index: Gets content by position. Use this when you need a message at a specific index rather than by role.
  • genai_extract_user_prompt: Extracts the last user prompt. Use this shorthand when you specifically need the most recent user message.
  • genai_extract_assistant_response: Extracts the last assistant response. Use this shorthand when you specifically need the most recent AI response.
  • genai_extract_system_prompt: Extracts the system prompt. Use this shorthand when you specifically need the system message.
  • genai_message_roles: Lists all roles in the conversation. Use this to understand what roles are present before extracting by role.