SocialToAIStart freeConsole

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`).

POSThttps://socialtoai.app/v1/schedules

Who 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
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  }'
FieldTypeRequiredWhat it is
toolstringOne of threeA ready-made tool's id: each run runs the tool.
actionstringOne of threeOne of the actions, such as search: each run makes that call.
opstringOne of threeA platform-specific interface, written platform.name, as POST /v1/call/{op} takes it.
inputobjectYesThe 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.
namestring | nullNoYour own name for it, up to 80 characters.
frequency"daily" | "weekly"YesEvery day, or every week.
weekdayintegerWeekly only0 for Sunday to 6 for Saturday.
timestringYesHH:MM, 24-hour, in timezone.
timezonestringYesAn IANA time zone such as Europe/London. The time follows its clock changes.
max_credits_per_runintegerYesThe most one run may cost. A run that would cost more is skipped, not charged.
alert_percentintegerNo1 to 1,000. A run whose main number moved by more than this percent from the last run's is an alert.
pausedbooleanChanges onlytrue pauses it; false takes it up again from its next time. Nothing missed meanwhile is run.
email_new_itemsbooleanNotrue 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_urlstring | nullNoThe 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:

201 Created2010 credits
{  "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

MethodPathWhat it does
POST/v1/schedulesMake a schedule. Answers 201 with the schedule and quote_credits, what a run costs now.
GET/v1/schedulesYour 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}/deleteDelete it. What its runs were charged stays in your usage.
POST/v1/schedules/{id}/runRun it now, apart from its times. Not counted in the month's cap.
GET/v1/schedules/{id}/runsThe latest 100 times it came due: run, or skipped and why.
POST/v1/schedules/{id}/feedIts 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}/feed and {"action": "rotate"} (or “New address” in the console, or rotate_feed over 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.

ChatAddressIn the chat
Feishu / Larkhttps://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.
WeComhttps://qyapi.weixin.qq.com/cgi-bin/webhook/send?…Group → … → Add group bot → copy its Webhook address.
Slackhttps://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_items in the runs list, the email and schedule_run.finished count them.
  • Each run is charged when it ends, at the prices in force then. A run that would cost more than max_credits_per_run is skipped.
  • The month's cap is max_credits_per_run times 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 /run is 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_reasonWhy
previous_run_not_finishedThe run before it is still going.
key_not_usableThe 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_paidThe account has not bought credits, and runs only its first schedule.
plan_limitA free account cannot run what it runs at this scale.
unavailableWhat it runs is not offered right now.
over_run_limitAt the prices in force, a run costs more than max_credits_per_run.
monthly_capThe run would pass this month's cap.
insufficient_balanceThe balance does not cover the run.
daily_limit_reachedA daily cap of the key or the account is reached.
rate_limitedToo much was running at once.
another codeThe 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: