# Engage actions

> Engage: 12 Xholic actions (5 read, 7 change), each with its MCP tool, REST endpoint and CLI command.

Source: https://docs.xholic.ai/actions/engage/

12 actions. Every field marked *Required* must be sent; `account`, `dryRun`, `idempotencyKey`, `confirmCredits` and `quoteId` are the [control fields](/api/responses/#control-fields) every surface adds.

## Who to engage now

`engage.who_to_engage` · read

People worth replying to right now and why: unanswered mentions, the account's reply circle, and warm Signals leads. Write the replies yourself in the user's voice (get_me), then post with schedule_post or publish_now using replyTo only if the user asks.

- **MCP tool:** `who_to_engage`. Loaded by default in MCP clients.
- **REST:** `GET /v1/engage/who-to-engage`
- **CLI:** `xholic engage who-to-engage`
- **Scope:** `read`
- **Plan:** Every plan, including the trial
- **Cost:** Free.
- **Rate limit bucket:** `read`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer 1–30 | No |  |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |

## Reply circle

`engage.reply_circle` · read

The people the account trades replies with most, and who to reply to next to grow.

- **MCP tool:** `engage_reply_circle`. Catalog: reach it with `find_actions` and `run_read_action`, or turn on the full toolset.
- **REST:** `GET /v1/engage/reply-circle`
- **CLI:** `xholic engage reply-circle`
- **Scope:** `read`
- **Plan:** Every plan, including the trial
- **Cost:** Free.
- **Rate limit bucket:** `read`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer 1–10 | No | Fresh posts to return. Default: `5`. |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |

## Engage guidelines status

`engage.get_consent` · read

Whether the user accepted Engage's guidelines. Engage feeds, mentions and replies need it; until then they answer with a consent error.

- **MCP tool:** `engage_get_consent`. Catalog: reach it with `find_actions` and `run_read_action`, or turn on the full toolset.
- **REST:** `GET /v1/engage/get-consent`
- **CLI:** `xholic engage get-consent`
- **Scope:** `read`
- **Plan:** Every plan, including the trial
- **Cost:** Free.
- **Rate limit bucket:** `read`

**Input**

No input.

## Accept Engage guidelines

`engage.accept_consent` · write

Record that the user accepted Engage's guidelines for engaging on X. Tell the user they are accepting them and call it only after they explicitly agree in the conversation; never on your own initiative.

- **MCP tool:** `engage_accept_consent`. Catalog: reach it with `find_actions` and `run_write_action`, or turn on the full toolset.
- **REST:** `POST /v1/engage/accept-consent`
- **CLI:** `xholic engage accept-consent`
- **Scope:** `write`
- **Plan:** Every plan, including the trial
- **Cost:** Free.
- **Rate limit bucket:** `write`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | "v2" | Yes |  |
| `dryRun` | boolean | No | Return exactly what would happen without doing it. |
| `idempotencyKey` | string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |

## Engage feeds

`engage.list_feeds` · read

The account's saved Engage feeds (FEEDS) or extension timelines (TIMELINE).

- **MCP tool:** `engage_list_feeds`. Catalog: reach it with `find_actions` and `run_read_action`, or turn on the full toolset.
- **REST:** `GET /v1/engage/list-feeds`
- **CLI:** `xholic engage list-feeds`
- **Scope:** `read`
- **Plan:** Every plan, including the trial
- **Cost:** Free.
- **Rate limit bucket:** `read`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `placement` | "FEEDS" \\| "TIMELINE" | No |  |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |

## Create an Engage feed

`engage.create_feed` · write

Save a feed of posts to engage with: a topic, a contact list, an X list, or one account (timelines only). Call it only when the user asked for this in the conversation; never on your own initiative.

- **MCP tool:** `engage_create_feed`. Catalog: reach it with `find_actions` and `run_write_action`, or turn on the full toolset.
- **REST:** `POST /v1/engage/create-feed`
- **CLI:** `xholic engage create-feed`
- **Scope:** `write`
- **Plan:** Every plan, including the trial
- **Cost:** Free.
- **Rate limit bucket:** `write`
- **Undo:** from the activity log, which runs `engage.delete_feed`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string ≤ 80 chars | Yes |  |
| `type` | "TOPIC" \\| "FOLLOWING" \\| "CONTACT_LIST" \\| "X_LIST" \\| "USER" | Yes | TOPIC (query holds 1-5 keywords), CONTACT_LIST (contactListId), X_LIST (xListId), USER (query holds a handle; TIMELINE placement only). |
| `placement` | "FEEDS" \\| "TIMELINE" | No | FEEDS (default) or TIMELINE. It can't change later. |
| `query` | string ≤ 500 chars or null | No |  |
| `contactListId` | string (uuid) or null | No |  |
| `xListId` | string or null | No |  |
| `excludedHandles` | array of string ≤ 16 chars (max 50) | No |  |
| `excludedTerms` | array of string ≤ 80 chars (max 50) | No |  |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |
| `dryRun` | boolean | No | Return exactly what would happen without doing it. |
| `idempotencyKey` | string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |

## Create several Engage feeds

`engage.create_feeds` · write

Save up to 8 Engage feeds in one call. Call it only when the user asked for this in the conversation; never on your own initiative.

- **MCP tool:** `engage_create_feeds`. Catalog: reach it with `find_actions` and `run_write_action`, or turn on the full toolset.
- **REST:** `POST /v1/engage/create-feeds`
- **CLI:** `xholic engage create-feeds`
- **Scope:** `write`
- **Plan:** Every plan, including the trial
- **Cost:** Free.
- **Rate limit bucket:** `write`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `feeds` | array of object (min 1, max 8) | Yes |  |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |
| `dryRun` | boolean | No | Return exactly what would happen without doing it. |
| `idempotencyKey` | string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |

## Edit an Engage feed

`engage.update_feed` · write

Change a saved feed. Send the whole feed (name, type, query...); placement can't change. Call it only when the user asked for this in the conversation; never on your own initiative.

- **MCP tool:** `engage_update_feed`. Catalog: reach it with `find_actions` and `run_write_action`, or turn on the full toolset.
- **REST:** `POST /v1/engage/update-feed`
- **CLI:** `xholic engage update-feed`
- **Scope:** `write`
- **Plan:** Every plan, including the trial
- **Cost:** Free.
- **Rate limit bucket:** `write`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | Yes | Feed id from engage.list_feeds. |
| `name` | string ≤ 80 chars | Yes |  |
| `type` | "TOPIC" \\| "FOLLOWING" \\| "CONTACT_LIST" \\| "X_LIST" \\| "USER" | Yes | TOPIC (query holds 1-5 keywords), CONTACT_LIST (contactListId), X_LIST (xListId), USER (query holds a handle; TIMELINE placement only). |
| `placement` | "FEEDS" \\| "TIMELINE" | No | FEEDS (default) or TIMELINE. It can't change later. |
| `query` | string ≤ 500 chars or null | No |  |
| `contactListId` | string (uuid) or null | No |  |
| `xListId` | string or null | No |  |
| `excludedHandles` | array of string ≤ 16 chars (max 50) | No |  |
| `excludedTerms` | array of string ≤ 80 chars (max 50) | No |  |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |
| `dryRun` | boolean | No | Return exactly what would happen without doing it. |
| `idempotencyKey` | string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |

## Delete an Engage feed

`engage.delete_feed` · write

Delete a saved Engage feed. Call it only when the user asked for this in the conversation; never on your own initiative.

- **MCP tool:** `engage_delete_feed`. Catalog: reach it with `find_actions` and `run_write_action`, or turn on the full toolset.
- **REST:** `POST /v1/engage/delete-feed`
- **CLI:** `xholic engage delete-feed`
- **Scope:** `write`. Destructive: it can't be taken back
- **Plan:** Every plan, including the trial
- **Cost:** Free.
- **Rate limit bucket:** `write`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | Yes | Feed id from engage.list_feeds. |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |
| `dryRun` | boolean | No | Return exactly what would happen without doing it. |
| `idempotencyKey` | string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |

## Read an Engage feed

`engage.feed` · read

Posts to engage with from a saved feed (feedId) or an ad-hoc topic search (type TOPIC + query), top or latest. Posts the user already replied to are hidden by default.

- **MCP tool:** `engage_feed`. Catalog: reach it with `find_actions` and `run_read_action`, or turn on the full toolset.
- **REST:** `GET /v1/engage/feed`
- **CLI:** `xholic engage feed`
- **Scope:** `read`
- **Plan:** Every plan, including the trial
- **Cost:** Live X lookup: no credits, counts toward the plan's X data limits.
- **Rate limit bucket:** `live_x`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `feedId` | string (uuid) | No |  |
| `type` | "TOPIC" \\| "FOLLOWING" \\| "CONTACT_LIST" \\| "X_LIST" \\| "USER" | No |  |
| `query` | string ≤ 500 chars | No |  |
| `sort` | "TOP" \\| "LATEST" | No |  |
| `cursor` | string ≤ 2000 chars | No | From the previous page, for more. |
| `hideReplied` | boolean | No |  |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |

## Hide or mark a post replied

`engage.set_item_state` · write

Hide a post from Engage feeds (a skip), or mark it replied or not replied.

- **MCP tool:** `engage_set_item_state`. Catalog: reach it with `find_actions` and `run_write_action`, or turn on the full toolset.
- **REST:** `POST /v1/engage/set-item-state`
- **CLI:** `xholic engage set-item-state`
- **Scope:** `write`
- **Plan:** Every plan, including the trial
- **Cost:** Free.
- **Rate limit bucket:** `write`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tweetId` | string | Yes | X post id (digits). |
| `hidden` | boolean | No |  |
| `replied` | boolean | No |  |
| `accountId` | string | No | The post author's X user id, when known. |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |
| `dryRun` | boolean | No | Return exactly what would happen without doing it. |
| `idempotencyKey` | string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |

## Clear hidden posts

`engage.clear_skips` · write

Bring back every post the account hid from Engage feeds. Call it only when the user asked for this in the conversation; never on your own initiative.

- **MCP tool:** `engage_clear_skips`. Catalog: reach it with `find_actions` and `run_write_action`, or turn on the full toolset.
- **REST:** `POST /v1/engage/clear-skips`
- **CLI:** `xholic engage clear-skips`
- **Scope:** `write`
- **Plan:** Every plan, including the trial
- **Cost:** Free.
- **Rate limit bucket:** `write`

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |
| `dryRun` | boolean | No | Return exactly what would happen without doing it. |
| `idempotencyKey` | string ≤ 200 chars | No | A unique key for this write. Repeating a call with the same key returns the first result instead of acting twice. |