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

# Captures

> Extract and store values from step execution.

## Overview

**Captures** extract values from a step's result and store them as variables for use in subsequent steps. Add a `captures` array to any step.

## Example

```yaml theme={null}
steps:
  - ordinal: 0
    description: "Navigate to order page"
    action:
      type: navigate
      url: "https://app.example.com/orders/123"
    url: "https://app.example.com/orders/123"
    riskLevel: low
    requiresConfirmation: false
    captures:
      - name: orderId
        strategy: url
        pattern: "/orders/(\\d+)"
        group: 1
      - name: pageTitle
        strategy: snapshot
        description: "Page heading text"
      - name: totalAmount
        strategy: ai
        prompt: "What is the total order amount displayed on the page?"
```

## Capture fields

| Field         | Type            | Required | Description                                                         |
| ------------- | --------------- | :------: | ------------------------------------------------------------------- |
| `name`        | string          |    Yes   | Variable name to store the captured value                           |
| `strategy`    | CaptureStrategy |    Yes   | Extraction method (see below)                                       |
| `description` | string          |    No    | Human-readable description                                          |
| `required`    | boolean         |    No    | If `true`, step fails when capture returns empty (default: `false`) |
| `pattern`     | string          |    No    | Regex pattern for text extraction                                   |
| `group`       | integer         |    No    | Regex capture group index (0-based)                                 |
| `prompt`      | string          |    No    | AI prompt for `ai` strategy                                         |
| `expression`  | string          |    No    | Template expression for `expression` strategy                       |

## Capture strategies

### `snapshot`

Capture a value from the current page DOM. Use `pattern` to extract a substring.

```yaml theme={null}
captures:
  - name: confirmationCode
    strategy: snapshot
    description: "Confirmation code shown after submission"
    pattern: "Code:\\s*(\\w+)"
    group: 1
```

### `url`

Extract from the current page URL.

```yaml theme={null}
captures:
  - name: orderId
    strategy: url
    pattern: "/orders/(\\d+)"
    group: 1
```

### `ai`

Use AI to extract a value from the page. Provide a `prompt` describing what to extract.

```yaml theme={null}
captures:
  - name: statusMessage
    strategy: ai
    prompt: "What is the status message displayed in the alert banner?"
```

### `expression`

Evaluate a template expression. Useful for transforming or combining captured values.

```yaml theme={null}
captures:
  - name: fullUrl
    strategy: expression
    expression: "https://app.example.com/orders/{{orderId}}"
```

### `evaluate`

Run JavaScript in the page context and capture the result.

```yaml theme={null}
captures:
  - name: itemCount
    strategy: evaluate
    expression: "document.querySelectorAll('.item-row').length.toString()"
```

## Using captured values

Captured values are available as template variables in subsequent steps:

```yaml theme={null}
steps:
  - ordinal: 0
    description: "Extract order ID from URL"
    action:
      type: navigate
      url: "https://app.example.com/orders/123"
    url: "https://app.example.com/orders/123"
    riskLevel: low
    requiresConfirmation: false
    captures:
      - name: orderId
        strategy: url
        pattern: "/orders/(\\d+)"
        group: 1
  - ordinal: 1
    description: "Navigate to order details"
    action:
      type: navigate
      url: "https://app.example.com/orders/{{orderId}}/details"
    url: "https://app.example.com/orders/{{orderId}}/details"
    riskLevel: low
    requiresConfirmation: false
```

## Regex patterns

When using `pattern`, the value must be a valid regular expression. Use `group` to select a specific capture group:

* `group: 0` — Entire match (default)
* `group: 1` — First capture group
* `group: 2` — Second capture group

```yaml theme={null}
captures:
  - name: price
    strategy: snapshot
    pattern: "\\$([\\d,]+\\.\\d{2})"
    group: 1
    # Captures "1,234.56" from "$1,234.56"
```