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://api.socialtoai.com/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. pause, resume and delete take its id. Ask “what's new?” and watch_news answers what your watches found that you have not seen, newest first, for free.

A successful search or Brand buzz, Account watch, 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://api.socialtoai.com/v1/schedules \  -H "Authorization: Bearer $SOCIALTOAI_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.

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"  },  "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.

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.

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_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: 2026-10-25