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

# Keyword Warmup

> Build valid keyword warmup requests, including prompt and comment-plan requirements.

# Keyword Warmup

`keyword_warmup` is the most automation-ready public capability. It is currently:

* implemented
* live verified
* allowed for unattended use

## What It Does

Phonefarm turns one capability request into a `search_warmup_session` execution plan that:

* searches one or more keywords
* watches result videos
* optionally likes, saves, and comments based on configured probabilities

## Minimal Request

```json theme={null}
{
  "request_id": "warmup-2026-03-22-001",
  "capability": "keyword_warmup",
  "mode": "manual",
  "target": {
    "routing": "direct",
    "phone_id": "phone_01",
    "account_id": "account_user095916355"
  },
  "inputs": {
    "keywords": ["healthy dinner ideas", "meal prep"],
    "videos_per_keyword": 2,
    "interaction_mode": "smart",
    "comment_probability": 0
  },
  "callback": {
    "url": "https://ugc-tracker.example.com/phonefarm/process-updates",
    "metadata": {}
  },
  "requested_by": {
    "system": "ugc-tracker",
    "user": "operator@example.com",
    "metadata": {}
  }
}
```

## Inputs

| Field                         | Type                  | Notes                                                                    |
| ----------------------------- | --------------------- | ------------------------------------------------------------------------ |
| `keywords`                    | string\[]             | Preferred multi-keyword form.                                            |
| `keyword`                     | string                | Single-keyword fallback.                                                 |
| `videos`                      | integer               | Simple fixed count per session.                                          |
| `videos_per_keyword`          | integer or integer\[] | Number or explicit per-keyword array.                                    |
| `videos_min`                  | integer               | Optional lower bound.                                                    |
| `videos_max`                  | integer               | Optional upper bound.                                                    |
| `interaction_mode`            | string                | `light`, `smart`, or `engaged`.                                          |
| `like_probability`            | number                | Optional override.                                                       |
| `save_probability`            | number                | Optional override.                                                       |
| `comment_probability`         | number                | Optional override.                                                       |
| `comment_plan`                | object                | Keyword-keyed map of comment candidates.                                 |
| `keyword_comment_plan_prompt` | object                | Required when comments are enabled and explicit comment\_plan is absent. |
| `dismiss_app_on_finish`       | boolean               | Defaults to `true`.                                                      |

## Interaction Modes

| Mode      | Default comment probability |
| --------- | --------------------------- |
| `light`   | `0.03`                      |
| `smart`   | `0.08`                      |
| `engaged` | `0.14`                      |

## Comment Rules

If the effective comment probability is greater than `0`:

* either provide `comment_plan`
* or provide `keyword_comment_plan_prompt`

### `comment_plan` rules

* must be an object
* keys must match the resolved keyword set exactly
* each keyword bucket must contain at least one non-empty comment string

Example:

```json theme={null}
{
  "healthy dinner ideas": [
    "this is actually useful",
    "saving this one for later"
  ],
  "meal prep": [
    "needed this reminder honestly",
    "this was way more practical than most meal prep tips"
  ]
}
```

## Routing Guidance

* Use `direct` for agent-like or immediate single-target execution.
* Use `queue` when your control plane wants Phonefarm to materialize work later.
* Use `group` for explicit multi-target fanout.

## Failure Cases To Expect

* duplicate keywords
* unknown interaction mode
* missing comment prompt when comments are enabled
* malformed comment plan

## Read Next

* [Capability Requests](../api/capability-requests)
* [Capability Registry](../reference/capability-registry)
* [Errors and Idempotency](../reference/errors-and-idempotency)