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

# Use Cases

> Example workflows for the Moda Data API

## Monitoring User Frustration

Use the frustration tools to identify and investigate unhappy users.

**Workflow:**

1. Start with `moda_get_overview` to see the frustration rate
2. Use `moda_get_frustrations` to get specific frustrated conversations with evidence
3. Drill into a conversation with `moda_get_conversation_context` to see the full context

**Example prompt for Claude Code:**

> "Check if any users were frustrated in the last 7 days and show me the details"

## Investigating Tool Failures

Identify which tools are failing and why.

**Workflow:**

1. Call `moda_get_tool_failures` to see which tools have the most failures
2. Pick a tool and call `moda_get_tool_failure_detail` to see error subtypes and examples
3. Use the inline conversation context in each example to understand the failure scenario

**Example prompt for Claude Code:**

> "Which tools are failing the most? Show me examples of the top failing tool"

## Exploring Conversation Clusters

Understand what topics your users are discussing.

**Workflow:**

1. Call `moda_get_clusters` to see root-level topic categories
2. Drill into a category by passing its `node_id` as `parent_id`
3. Use `moda_get_cluster_conversations` to see specific conversations in a cluster

**Example prompt for Claude Code:**

> "What are the main topics users are asking about? Drill into the biggest cluster"

## Searching Conversations

Find specific conversations by content, user, or time range.

**Workflow:**

1. Use `moda_search_conversations` with a `search` term for full-text search
2. Filter by `environment` to focus on production vs. development
3. Use `moda_get_conversation_context` to read specific conversations

**Example prompt for Claude Code:**

> "Find all production conversations mentioning 'timeout errors' from the last 24 hours"

## Finding Conversations by World State

The agent's **world state** captures what it has learned in a conversation — structured
slots plus a durable per-user profile. Search across it with keywords to surface
conversations that involve a particular fact, goal, or user attribute, and combine it with
`--outcome` to focus on good or bad runs.

```bash theme={"dark"}
# Positive (successful, non-frustrated) conversations whose world state mentions "enterprise"
moda conversations --world-state="enterprise" --outcome=positive

# AND multiple keywords, and attach the matched world state to each result
moda conversations --world-state="refund,billing" --include-world-state

# Drill into one conversation's slots, open threads, and how they were learned
moda world-state <conversation_id>
```

Keyword matching is a case-insensitive substring over the full world-state content
(segment slots **and** carried-in durable profile), so you don't need to know the exact
slot key — useful while slot naming is still evolving.

**Example prompt for Claude Code:**

> "Find positive conversations where the user is on an enterprise plan, then show me the world state for the first one"