> ## Documentation Index
> Fetch the complete documentation index at: https://axiom.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# genai_get_role

> This page explains how to use the genai_get_role function in APL.

The `genai_get_role` function retrieves the role of a message at a specific position in a GenAI messages array. This allows you to understand who sent a particular message in the conversation (user, assistant, system, tool, etc.).

You can use this function to validate conversation structure, analyze message patterns, verify conversation flow, or process conversations based on role sequences.

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

<AccordionGroup>
  <Accordion title="Splunk SPL users">
    In Splunk SPL, you would use `mvindex` to access the role field at a specific position.

    <CodeGroup>
      ```sql Splunk example theme={null}
      | eval message_role=mvindex(role, 2)
      ```

      ```kusto APL equivalent theme={null}
      ['ai-logs']
      | extend message_role = genai_get_role(messages, 2)
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="ANSI SQL users">
    In ANSI SQL, you would unnest the array and access the role at a specific offset.

    <CodeGroup>
      ```sql SQL example theme={null}
      SELECT 
        conversation_id,
        role as message_role
      FROM conversations
      CROSS JOIN UNNEST(messages) WITH OFFSET AS pos
      WHERE pos = 2
      ```

      ```kusto APL equivalent theme={null}
      ['ai-logs']
      | extend message_role = genai_get_role(messages, 2)
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## Usage

### Syntax

```kusto theme={null}
genai_get_role(messages, index)
```

### Parameters

| Name     | Type    | Required | Description                                                                                                                 |
| -------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| messages | dynamic | Yes      | An array of message objects from a GenAI conversation. Each message typically contains `role` and `content` fields.         |
| index    | long    | Yes      | The zero-based position of the message whose role you want to retrieve. Use 0 for the first message, 1 for the second, etc. |

### Returns

Returns a string containing the role of the message at the specified index (such as 'user', 'assistant', 'system', 'tool', 'function'), or an empty string if the index is out of bounds.

## Example

Get the role of the first message in a GenAI conversation.

**Query**

```kusto theme={null}
['otel-demo-genai']
| extend first_role = genai_get_role(['attributes.gen_ai.input.messages'], 0)
| summarize conversations_with_system = countif(first_role == 'system'), total_conversations = count()
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27otel-demo-genai%27%5D%20%7C%20extend%20first_role%20%3D%20genai_get_role\(%5B%27attributes.gen_ai.input.messages%27%5D%2C%200\)%20%7C%20summarize%20conversations_with_system%20%3D%20countif\(first_role%20%3D%3D%20%27system%27\)%2C%20total_conversations%20%3D%20count\(\)%22%7D)

**Output**

| conversations\_with\_system | total\_conversations |
| --------------------------- | -------------------- |
| 1250                        | 1450                 |

This query verifies that most conversations are properly initialized with system prompts.

## List of related functions

* [genai\_get\_content\_by\_index](/apl/scalar-functions/genai-functions/genai-get-content-by-index): Gets content at a specific index. Combine with genai\_get\_role to understand both role and content at positions.
* [genai\_message\_roles](/apl/scalar-functions/genai-functions/genai-message-roles): Lists all roles in the conversation. Use this to get a complete picture of all roles rather than checking individual positions.
* [genai\_get\_content\_by\_role](/apl/scalar-functions/genai-functions/genai-get-content-by-role): Gets content filtered by role. Use this when you need content from a specific role type.
* [array\_length](/apl/scalar-functions/array-functions/array-length): Returns the total number of messages. Use this to validate index bounds before accessing positions.