# Scheduler actions

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

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

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.

## Scheduler settings

`scheduler.get_settings` · read

The account's scheduler settings: timezone, posting window, quote fallback and default post automations with saved templates.

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

**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. |

## Update scheduler settings

`scheduler.update_settings` · publish

Replace the scheduler timezone and default post automations (with templates). Read scheduler.get_settings first and send the whole automation object back with your changes. Call it only when the user asked for this in the conversation; never on your own initiative.

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

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `timezone` | string ≤ 100 chars | Yes | IANA timezone such as America/New_York. Use the user's timezone. |
| `automation` | object | Yes | The full default automation settings as returned by scheduler.get_settings, including templates. |
| `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. |

## Set the posting window

`scheduler.set_posting_window` · write

Set the hours of the day posts may go out at, or clear it with null. Next-slot and best-time scheduling stay inside it. Call it only when the user asked for this in the conversation; never on your own initiative.

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

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `timezone` | string ≤ 100 chars | Yes | IANA timezone such as America/New_York. Use the user's timezone. |
| `postingWindow` | object or null | Yes |  |
| `postingWindow.startMinutes` | integer 0–1439 | Yes | Minutes after local midnight, e.g. 540 for 9:00. |
| `postingWindow.endMinutes` | integer 0–1439 | Yes | Minutes after local midnight; must differ from start. |
| `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. |

## Set the quote fallback

`scheduler.set_quote_fallback` · write

Choose what happens when a scheduled quote post's original is gone at publish time: post without the quote, or fail the post. Call it only when the user asked for this in the conversation; never on your own initiative.

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

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `timezone` | string ≤ 100 chars | Yes | IANA timezone such as America/New_York. Use the user's timezone. |
| `quoteUnavailableAction` | "SEND_WITHOUT_QUOTE" \\| "FAIL_POST" | 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. |

## Look up a post to quote

`scheduler.lookup_quote` · read

Preview the X post behind a URL before quoting it: author, text, time and media.

- **MCP tool:** `scheduler_lookup_quote`. Catalog: reach it with `find_actions` and `run_read_action`, or turn on the full toolset.
- **REST:** `GET /v1/scheduler/lookup-quote`
- **CLI:** `xholic scheduler lookup-quote`
- **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 |
| --- | --- | --- | --- |
| `url` | string ≤ 2048 chars | Yes | The X post URL. |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |

## Parse a schedule time

`scheduler.parse_time` · read

Turn words like "tomorrow 9am" or "next friday at noon" into an exact ISO time in the account's timezone. Changes nothing.

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

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | string ≤ 200 chars | Yes |  |
| `timezone` | string ≤ 100 chars | Yes | IANA timezone such as America/New_York. Use the user's timezone. |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |

## Calendar view

`scheduler.schedule_view` · read

The posting calendar day by day: scheduled posts, open slots and best times, for up to 42 days.

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

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tagIds` | string ≤ 1900 chars | No | Comma-separated tag ids from list_tags, to show only posts with those tags. |
| `timezone` | string ≤ 100 chars | No | IANA timezone such as America/New_York. Use the user's timezone. |
| `days` | integer 1–42 | No | Days to show (default 21). |
| `startDate` | string (date) | No | First day, YYYY-MM-DD. Defaults to today. |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |

## Scheduler summary

`scheduler.dashboard_summary` · read

What needs attention in the scheduler: failed posts, failed automations and what's coming up next.

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

**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. |

## Dismiss a scheduler alert

`scheduler.acknowledge_alert` · write

Mark a failed post or failed automation alert from scheduler.dashboard_summary as seen so it stops showing.

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

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | "POST" \\| "AUTOMATION" | Yes |  |
| `postId` | string ≤ 120 chars | Yes | Xholic scheduled post id, from get_queue. |
| `ruleId` | string ≤ 120 chars | No | Required when kind is AUTOMATION. |
| `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. |

## Best times to post

`scheduler.best_times` · read

The best upcoming times for this account to post, from when its audience engages. Use before scheduling when the user wants a good time rather than a set one.

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

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `timezone` | string ≤ 100 chars | No | IANA timezone such as America/New_York. Use the user's timezone. |
| `slotCount` | integer 1–140 | No | How many times to return (default 12). |
| `windowStartMinutes` | integer 0–1439 | No | Only times after this, in minutes after local midnight. Send with windowEndMinutes. |
| `windowEndMinutes` | integer 0–1439 | No | Only times before this, in minutes after local midnight. Send with windowStartMinutes. |
| `account` | string ≤ 64 chars | No | X account to act on, as @handle. Leave it out to use the connection's default account. |

## Weekly posting slots

`scheduler.list_slots` · read

The account's weekly posting slots that "next slot" scheduling fills.

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

**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. |

## Replace weekly posting slots

`scheduler.replace_slots` · write

Replace every weekly posting slot with this list. Slots left out are removed, so read scheduler.list_slots first. Call it only when the user asked for this in the conversation; never on your own initiative.

- **MCP tool:** `scheduler_replace_slots`. Catalog: reach it with `find_actions` and `run_write_action`, or turn on the full toolset.
- **REST:** `POST /v1/scheduler/replace-slots`
- **CLI:** `xholic scheduler replace-slots`
- **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 |
| --- | --- | --- | --- |
| `slots` | array of object (max 140) | 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. |