Schedules
A schedule runs a ready-made tool, an action or a platform-specific interface every day or every week at a time in your time zone, and delivers only what is new since the run before. Each run is an ordinary call, charged when it ends; one that would cost more than its limit is skipped, free. Make one with a key, in the console, or by asking your AI app (MCP `watch`).
https://socialtoai.app/v1/schedulesWho can make one
- Any account. One that has not bought credits keeps 1 schedule, run from its free credits: when they no longer cover a run, it is paused, you get one email, and it resumes by itself after you buy credits. A second one answers HTTP 403
plan_limit. - With a key that has the permission to manage schedules (set in the key's settings in the console); without it, HTTP 403
key_scope_denied. Or in the console: open a result and choose “Make it recurring”, then manage it on the Tasks page. - At most 20 schedules per account that has bought credits. A schedule runs as the key that made it: when that key is revoked or expires, the schedule stops.
From your AI app
Over MCP the same schedules are called watches. Say “watch this every morning” and your AI app calls watch twice: action: "preview" answers what will run, when, about how many credits a run and at most a month (with dollars beside them), and where new items go, and charges nothing; only after you agree, action: "confirm" with the preview's token makes it, exactly as previewed. action: "list" shows your watches with their feed addresses; pause, resume, delete, rotate_feed and revoke_feed take a watch's id. Ask “what's new?” and watch_news answers what your watches found that you have not seen, newest first, for free.
To have new items posted to a group chat, paste the chat's group bot address to your AI app: it is passed as delivery, and the preview names the chat before anything is made.
A successful search or Brand buzz, Account snapshot, Viral finder answer over MCP may end with watch_hint, one line that offers to watch it daily and what a run would cost; it comes at most once an hour, and never with an error.
Make a schedule
Name what it runs, the body of that request, when, and the most one run may cost. Making one is free: the request is quoted, and refused with HTTP 402 max_cost_exceeded and the quote when a run would cost more than max_credits_per_run.
curl https://socialtoai.app/v1/schedules \ -H "Authorization: Bearer $SOCIALTOAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Daily check", "action": "search", "input": { "platform": "reddit", "query": "saturn rings" }, "frequency": "daily", "time": "09:00", "timezone": "UTC", "max_credits_per_run": 4 }'| Field | Type | Required | What it is |
|---|---|---|---|
tool | string | One of three | A ready-made tool's id: each run runs the tool. |
action | string | One of three | One of the actions, such as search: each run makes that call. |
op | string | One of three | A platform-specific interface, written platform.name, as POST /v1/call/{op} takes it. |
input | object | Yes | The body the call or the tool takes, platform included. max_cost_credits and confirm are left out: the schedule's own limit stands for them. |
name | string | null | No | Your own name for it, up to 80 characters. |
frequency | "daily" | "weekly" | Yes | Every day, or every week. |
weekday | integer | Weekly only | 0 for Sunday to 6 for Saturday. |
time | string | Yes | HH:MM, 24-hour, in timezone. |
timezone | string | Yes | An IANA time zone such as Europe/London. The time follows its clock changes. |
max_credits_per_run | integer | Yes | The most one run may cost. A run that would cost more is skipped, not charged. |
alert_percent | integer | No | 1 to 1,000. A run whose main number moved by more than this percent from the last run's is an alert. |
paused | boolean | Changes only | true pauses it; false takes it up again from its next time. Nothing missed meanwhile is run. |
email_new_items | boolean | No | true emails you, after each run that found something, how many items are new and the links of the first of them. Off unless set; watches made from an AI app have it on. |
push_url | string | null | No | The incoming-webhook address of a Feishu (Lark), WeCom or Slack group bot: each run that found something posts the count and the first links to that chat. Sent one test message when set; null takes it away. See Group chats. |
The answer holds the schedule as every route shows it:
{ "request_id": "req_00000000-0000-4000-8000-000000000020", "schema_version": "v1", "schedule": { "id": "00000000-0000-4000-8000-000000000021", "name": "Daily check", "tool": null, "action": "search", "op": null, "input": { "platform": "reddit", "query": "saturn rings" }, "frequency": "daily", "weekday": null, "time": "09:00", "timezone": "UTC", "max_credits_per_run": 4, "monthly_cap_credits": 124, "month_spent_credits": 0, "alert_percent": 20, "status": "active", "stop_reason": null, "email_new_items": false, "source": "key", "next_run_at": "2026-10-26T09:00:00.000Z", "running": false, "last_main_number": null, "last_run": null, "created_at": "2026-10-25T08:00:00.000Z", "feed": { "rss": "https://socialtoai.app/v1/feeds/wf_00000000….xml", "json": "https://socialtoai.app/v1/feeds/wf_00000000….json" }, "push": null }, "quote_credits": 2}Example: ids and times are placeholders.
Change, pause, run now
| Method | Path | What it does |
|---|---|---|
| POST | /v1/schedules | Make a schedule. Answers 201 with the schedule and quote_credits, what a run costs now. |
| GET | /v1/schedules | Your account's schedules, with max_schedules (20) and month_runs. |
| GET | /v1/schedules/{id} | One schedule. |
| POST | /v1/schedules/{id} | Change it: any field but what it runs. paused: true pauses it, paused: false takes it up again. |
| POST | /v1/schedules/{id}/delete | Delete it. What its runs were charged stays in your usage. |
| POST | /v1/schedules/{id}/run | Run it now, apart from its times. Not counted in the month's cap. |
| GET | /v1/schedules/{id}/runs | The latest 100 times it came due: run, or skipped and why. |
| POST | /v1/schedules/{id}/feed | Its feed: {"action": "rotate"} gives it a new address (the old one stops working), {"action": "off"} switches it off. |
A new time, and a schedule taken up again, go on from the next time after now: nothing missed meanwhile is run. What a schedule runs cannot be changed; make another schedule for that. An unknown id answers HTTP 404 not_found.
Read it as a feed (RSS)
Every schedule has a private feed of what its runs found new, newest first, as RSS 2.0 (.xml) and as JSON Feed (.json): feed.rss and feed.json in the schedule, on the Tasks page in the console, and in watch action: "list". Add it to a feed reader, Slack's RSS app or anything that reads a feed URL.
- Each item links to the original post. For 24 hours after its run it carries the post's title and the start of its text; after that, its platform and date. No author names, and commenters are never named.
- Reading it is free and needs no key: the address is the key. Anyone who has it can read the feed, so share it only where you would share the items. A reader may keep it for a minute.
- Change the address with
POST /v1/schedules/{id}/feedand{"action": "rotate"}(or “New address” in the console, orrotate_feedover MCP), or switch it off with{"action": "off"}: the old address stops answering within a minute.
Post to a group chat
Set push_url to a group bot's incoming-webhook address and each run that found something new posts the count, the first five links, the credits it was charged and a link to the console to that chat, in the chat's own format. One chat per schedule; null takes it away.
| Chat | Address | In the chat |
|---|---|---|
| Feishu / Lark | https://open.feishu.cn/open-apis/bot/v2/hook/… | Group settings → Bots → Add bot → Custom bot. Leave signature verification and the IP allowlist off; a keyword check passes with the keyword SocialToAI. |
| WeCom | https://qyapi.weixin.qq.com/cgi-bin/webhook/send?… | Group → … → Add group bot → copy its Webhook address. |
| Slack | https://hooks.slack.com/services/… | An app with Incoming Webhooks, added to the channel. |
When you set it, the chat is sent one test message; a chat that does not take it is refused (HTTP 400 invalid_params) and nothing is saved. Messages are retried and paused like webhooks: after too many failed tries in a row, push.state is paused and you get one email; set the address again to resume. Pushing costs nothing, and carries links and numbers only.
What a run costs
- A ready-made tool is charged its scale's price and runs its whole plan each time.
- An action or a platform-specific interface reads its first page each time and is charged for that page. It delivers only what is new: what the last run already saw is left out.
- Of a ready-made tool's run, the items whose ids the run before did not have are what is new:
new_itemsin the runs list, the email andschedule_run.finishedcount them. - Each run is charged when it ends, at the prices in force then. A run that would cost more than
max_credits_per_runis skipped. - The month's cap is
max_credits_per_runtimes the most runs a month can hold: 31 for a daily schedule, 5 for a weekly one (monthly_cap_credits). A scheduled run that would pass it is skipped until the next month. A run you start with/runis counted apart. - Each time is run once. After an interruption on our side, only the latest time that passed is run.
When a run is skipped
A skipped time costs nothing. Its status in the runs list is skipped and skip_reason says why. We email you the first time a schedule is skipped for a reason on a UTC day, unless you switched off emails about runs in the console's settings.
| skip_reason | Why |
|---|---|
previous_run_not_finished | The run before it is still going. |
key_not_usable | The key it runs as cannot be used for it now: suspended, revoked or expired, or the permission to read data or run tools switched off. |
not_paid | The account has not bought credits, and runs only its first schedule. |
plan_limit | A free account cannot run what it runs at this scale. |
unavailable | What it runs is not offered right now. |
over_run_limit | At the prices in force, a run costs more than max_credits_per_run. |
monthly_cap | The run would pass this month's cap. |
insufficient_balance | The balance does not cover the run. |
daily_limit_reached | A daily cap of the key or the account is reached. |
rate_limited | Too much was running at once. |
| another code | The request no longer reads as one; the value is the error code it was refused with, as in Errors. |
When a schedule stops
A stopped schedule does not run again; status is stopped and stop_reason is key_revoked, key_expired or account_closed. You are emailed when the key was revoked or expired. When a new price would make a run cost more than its limit, you are emailed before that price takes effect, so that you can raise the limit.
Alerts and results
Every finished run sets its main number beside the last run's: a ready-made tool's own main number, or for an action the number of new items. When it moved by more than alert_percent (20 unless you set it), or is not zero after zero, the run is an alert: alerted is true and a schedule.alert event goes to your webhooks. Every finished run also sends schedule_run.finished.
Each run in the runs list carries its handle: read its answer at GET /v1/results/{handle} for 24 hours, free. See Results and handles.
Last updated: