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

# Walkthrough: create a segment with a wizard

> Trace a full segment creation flow end-to-end: user input, 6 API calls, 2 wizard steps, payloads, confirmation, and execution logs in 1,033ms.

<Note>
  **User input:** *"Create a segment of enterprise users who haven't logged in for 30 days."*
</Note>

## Step 1: Resolve the criteria

The AI begins by looking up available traits before constructing anything. It doesn't assume field names. It verifies them first.

<Frame caption="The AI scans existing segments and user traits before building the payload">
  <img alt="Create A Segment, Step 1" title="Create A Segment, Step 1" lightAlt="Create A Segment, Step 1" darkAlt="Create A Segment, Step 1" src="https://mintcdn.com/candu/sDpAhmar-Rs5KeSS/images/Create-a-segment,-Step-1-1.png?fit=max&auto=format&n=sDpAhmar-Rs5KeSS&q=85&s=dd98076c1f98d3caebf878470efcada6" className="dark:hidden" width="1680" height="1055" data-path="images/Create-a-segment,-Step-1-1.png" />

  <img alt="Create A Segment, Step 1" title="Create A Segment, Step 1" lightAlt="Create A Segment, Step 1" darkAlt="Create A Segment, Step 1" src="https://mintcdn.com/candu/sDpAhmar-Rs5KeSS/images/Create-a-segment,-Step-1.png?fit=max&auto=format&n=sDpAhmar-Rs5KeSS&q=85&s=2abaa7a3ad18e7ab2e41ec79c33e9228" className="hidden dark:block" width="1680" height="1055" data-path="images/Create-a-segment,-Step-1.png" />
</Frame>

### Tool call 1: look up "plan" traits

```text theme={null}
GET /api/autoComplete?finder=byUserTraits&q=plan

→ { results: [{ name: "plan", type: "string", count: 5432 }] }
```

### Tool call 2: look up "last login" traits

```text theme={null}
GET /api/autoComplete?finder=byUserTraits&q=last

→ { results: [{ name: "last_seen_at", type: "datetime", count: 5432 }] }
```

<Info>
  The AI uses `autocomplete_query` to verify real field names before building the payload. It doesn't guess.
</Info>

### Tool call 3: create the segment shell

```text theme={null}
POST /api/dashboard/segmentsDefinition

{ "name": "Enterprise Users - Inactive 30 Days",
  "description": "Enterprise plan users who haven't logged in for 30+ days" }

→ { "id": "seg_9x8y7z6w", "definition": null }
```

The shell is created with no definition — that gets applied in the next call, after the user confirms.

<Frame caption="The AI surfaces structured options for ambiguous inputs. The user can select or type a free-text answer">
  <img src="https://mintcdn.com/candu/sDpAhmar-Rs5KeSS/images/Create-a-segment,-tool-call-3.png?fit=max&auto=format&n=sDpAhmar-Rs5KeSS&q=85&s=60a0851201d33b0ca54400dfff869f69" alt="Create A Segment, Tool Call 3" width="1680" height="1055" data-path="images/Create-a-segment,-tool-call-3.png" />
</Frame>

### Confirmation panel

<Frame caption="The user sees the full resolved payload before anything executes. Nothing fires until they click Create Segment.">
  <img src="https://mintcdn.com/candu/sDpAhmar-Rs5KeSS/images/Create-an-segment,-Confirmation-panel.png?fit=max&auto=format&n=sDpAhmar-Rs5KeSS&q=85&s=9a85eec92a459e32b686d94e560e25db" alt="Create An Segment, Confirmation Panel" width="1680" height="1055" data-path="images/Create-an-segment,-Confirmation-panel.png" />
</Frame>

### Tool call 4: apply segment definition

```text theme={null}
POST /api/dashboard/segmentsDefinition?action=update&segmentId=seg_9x8y7z6w

{
  "definition": {
    "object": "All",
    "groups": [
      { "object": "Single", "type": "UserProperty",
        "traitName": "plan", "operation": { "type": "Equals", "operand": "enterprise" } },
      { "object": "Single", "type": "UserSeen",
        "userSeenRuleType": "LastSeen", "operation": { "type": "Outside", "operand": 30 } }
    ]
  }
}

→ { "id": "seg_9x8y7z6w", "memberCount": 247 }
```

## Step 2: Test the segment

The wizard advances automatically. At step 2 the wizard prompts: *"We've created your segment. Let's test it: do you have a user ID or email in mind?"*

### Tool call 5: look up user by email

```text theme={null}
GET /api/autoComplete?finder=byUserEmail&q=john@acme.com

→ { results: [{ userId: "usr_abc123", email: "john@acme.com" }] }
```

### Tool call 6: check membership

```text theme={null}
GET /api/dashboard/segmentMemberships/usr_abc123

→ { isMember: true, matchedRules: [
     { type: "UserProperty", traitName: "plan", matched: true },
     { type: "UserSeen", matched: true, daysSinceLastSeen: 45 }
   ] }
```

The AI responds: *"[john@acme.com](mailto:john@acme.com) is in this segment. Plan: enterprise. Last seen: 45 days ago. Your segment is working correctly."*

## Execution summary

| Action                   | Endpoint                               | Policy    | Time  | Status |
| ------------------------ | -------------------------------------- | --------- | ----- | ------ |
| `autocomplete_query`     | byUserTraits q=plan                    | Automatic | 87ms  | 200    |
| `autocomplete_query`     | byUserTraits q=last                    | Automatic | 92ms  | 200    |
| `segments_create`        | POST /api/dashboard/segmentsDefinition | Confirm   | 234ms | 201    |
| `segments_update`        | POST ...?action=update                 | Confirm   | 412ms | 200    |
| `autocomplete_query`     | byUserEmail                            | Automatic | 65ms  | 200    |
| `segment_membership_get` | usr\_abc123                            | Automatic | 143ms | 200    |

**6 actions · 1,033ms · 100% success**

The four reads ran silently. The two writes paused for user confirmation before firing.

## What if something fails

<Frame caption="Connection errors are handled gracefully. The user can retry or continue without the context">
  <img src="https://mintcdn.com/candu/sDpAhmar-Rs5KeSS/images/Create-a-segment,-What-if-something-fails.png?fit=max&auto=format&n=sDpAhmar-Rs5KeSS&q=85&s=8f22ad1f989cd427cea25de1aa3a8859" alt="Create A Segment, What If Something Fails" width="1680" height="1055" data-path="images/Create-a-segment,-What-if-something-fails.png" />
</Frame>

If the segments API times out on load, the wizard surfaces a connection error with two options: Retry, or Continue Anyway. If the user continues, the AI builds the segment from scratch without deduplication checks.