schedule_task
Save a multi-step WORKFLOW (upsert by name) and attach a recurring cron
schedule for its delivery.
Use this when the user wants a sequence of platform calls delivered ON A
SCHEDULE / repeatedly (e.g. "every weekday morning pull 8-K releases, screen
for cheap large-caps, and email me the overlaps as a table"). For a ONE-OFF
request, call the corresponding tools directly instead.
`steps` (shape in the parameter description): a transform applies its
instruction to the accumulated results of ALL prior steps (e.g. "intersect the
two event sets by symbol and build a table"), and each step's `label` keys its
result. The LAST step's output is what gets delivered, so end table/summary
workflows with a transform.
Allowlisted fetch endpoints (anything else is rejected with a 422 at save
time; `params` takes the same keys as the matching tool):
- POST, JSON-body params: "get-realtime-events" (`list_realtime_events`),
"list-upcoming-earnings-announcements" (`list_earnings_announcements`),
"predict-earnings-announcement-move" ({"symbols": [...]}),
"data-catalogue-exploration" ({"query": "..."}).
- GET, scalar query params only (no lists/dicts): "get-company-snapshot"
(requires {"symbol": "..."}), "get-strategy-performance-summary",
"get-strategy-track-record", "get-strategy-swaps", "get-stock-picks",
"list-tickers", "list-realtime-event-options", "get-sectors",
"get-sub-industries".
- EXPENSIVE — max 2 per workflow, and the cron must use a literal minute and
at most 4 literal hours (no sub-hourly / "*" fields): "screen-stocks"
(`screen_stocks`), "generate-research-report" ({"query": "..."}),
"create-full-report" (a full ~10 min rebuild every run; {"ticker": "..."} for
the symbol's standard report;
add "user_override": true plus the shaping lists `generate_report_for_stock`
takes — financial_items, ratios, as_reported_financial_items, revenue_segment,
technical_analysis_items, estimate_items, institutional_ownership CIKs — for a
custom one; the backend rejects the lists without the switch),
"optimize-symbols", "optimize-portfolio", "list-optimized-stock-picks".
Each user may hold at most 10 active schedules.
Returns `status` 201 (created) or 200 (updated) with `workflow_id` and
`task_name` ("wf:{email}:{name}"), the key that `list_scheduled_tasks` shows
and `delete_scheduled_task` takes.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Lowercase slug and upsert key (no spaces, colons, or uppercase); re-saving the same name updates the workflow and re-attaches its schedule. | |
| steps | Yes | Ordered 1-8 steps; the first must be a fetch. Fetch: {"kind": "fetch", "endpoint": "<allowlisted kebab-case path, no leading slash>", "params": {...}, "label": "..."}. Transform: {"kind": "transform", "instruction": "<=2000 chars, applied to all prior results>", "label": "..."}. `label` is an optional unique lowercase slug (default step_{i}). The last step's output is delivered. | |
| delivery | No | Where each run's output goes. | |
| description | No | Optional human-readable note saved with the workflow. | |
| regular_cron | Yes | Raw 5-field cron expression for when the workflow fires, e.g. "30 6 * * 1-5" (weekdays 06:30); validated server-side. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cron | No | The cron expression attached. | |
| name | No | The workflow name (upsert key). | |
| status | No | 201 when the workflow was created, 200 when an existing one was updated. | |
| scheduled | No | ||
| task_name | Yes | "wf:{email}:{name}" — the key list_scheduled_tasks shows and delete_scheduled_task takes. | |
| workflow_id | No | Id of the saved workflow definition. |