Scheduled Tasks
A scheduled task is a Deep research topic or a prompt that Erebine runs on a schedule, unattended, as the project. Each run is a turn in the task's own chat. Runs read; they never write to the workspace and never wait for an approval. Every task carries a per-run and a monthly token cap.
- runs as
- The project, attributed to the person who created the task
- delivers to
- The task's own chat, one turn per run
- schedules
- Once, every N hours, days or weeks, or five-field cron; runs at least an hour apart
- base path
/:project_id/v1/scheduled-tasks- availability
- On by default; a deployment can switch scheduled tasks off
Overview
A task names what to run (a research topic or a prompt), the model that runs it, when it runs, which read-only tools a run may call, and how many tokens a run and a month may use. At each time the schedule names, Erebine starts a run in the background. When the run ends, its answer lands in the task's chat, you are notified if you asked to be, and the project's webhooks hear about it if the task sends webhook events.
Where scheduled tasks are switched off, every route below answers
503 scheduled_tasks_unavailable, the web app drops Scheduled
from its top bar, Erebine Desktop hides its Scheduled destination, and chat offers no
schedule proposals.
Research and Prompt Tasks
| Kind | Definition | What a run does | Tools when tools is left out |
|---|---|---|---|
research |
topic, 1 to 2,000 characters; depth, deep (default) or auto |
A research turn: deep runs the Deep research pipeline, auto lets the model size the research (see Research Depth) |
Web search, Fetch pages, Inspect sites, Image search, Time, Weather, Calculator |
prompt |
prompt, 1 to 8,000 characters |
An ordinary turn on the prompt | Recall memories, Search memory, Project brief, Calculator |
A task's kind is fixed: an update that sends the other kind answers
400 invalid_definition. Delete the task and create another. A tool the
deployment or the workspace does not offer is left out of the default set.
Each run is given the task's name, the time it runs for, the topic or prompt, and, after the first completed run, the previous run's time and summary as quoted data. Nothing else in the chat is sent: a reply you write in the task's chat is an ordinary conversation and never steers a later run. The summary is the last section headed Summary in the previous answer, up to 4,000 characters, or the answer's first 2,000 characters when it has no such section.
Creating a Task
The web app, Erebine Desktop and erectl show the schedule, the next runs, the tools, the caps and the estimated cost, and schedule nothing until you confirm. The API creates the task on the call.
- The Scheduled page. Scheduled in the web app's top bar lists the project's tasks with their next run, last result and this month's usage, and New task opens the configuration card. Run now, Pause, Resume, Edit, Delete and Cancel run sit on each task you may act on.
- Schedule this. A finished reply that used the web research tools offers Schedule this beside Download research. The card starts from that turn: its question as the topic,
deepwhen the reply ran Deep research andautootherwise, the chat's model and workspace, and a weekly schedule on today's weekday at the current hour. - A proposed schedule. Ask in chat for something to happen regularly or later ("every Monday", "tomorrow at 9") and the model may propose a task with
x_propose_schedule. The proposal shows as a card; Review and schedule opens the configuration card, and Dismiss drops it. - Erebine Desktop. Scheduled in the sidebar, in Basic and Advanced, holds the same list and card. Desktop Chat offers Schedule this and proposal cards too.
- erectl.
erectl scheduled-taskscreates, prices and manages tasks from a terminal. - The API.
POST /v1/scheduled-tasks, afterPOST /v1/scheduled-tasks/estimateto price the draft.
Schedules
A schedule is one of three kinds, read in its timezone. Local times are written YYYY-MM-DDTHH:MM, with no seconds and no offset.
| Kind | Fields | Rules |
|---|---|---|
once |
at |
At least 60 seconds and at most 366 days ahead when the schedule is set or the task resumed. After its run the task is completed. |
interval |
every, unit, start_at (optional) |
hours 1 to 168, days 1 to 365, weeks 1 to 52. start_at defaults to the next whole local hour; one in the past starts at the next aligned time after now. |
cron |
expression |
The five-field cron dialect. |
{"kind": "once", "at": "2026-11-20T09:00", "timezone": "Europe/London"}
{"kind": "interval", "every": 6, "unit": "hours", "start_at": "2026-11-14T09:00", "timezone": "Europe/London"}
{"kind": "cron", "expression": "0 9 * * MON-FRI", "timezone": "America/Chicago"}
No two runs are less than an hour apart. When a schedule is set or a task resumed, the next
50 firings of a cron schedule are computed, and two closer than one hour answer
400 interval_too_short. A firing that still comes less than an hour after the
task's previous firing is skipped with interval_too_short; see
Time Zones and DST. A cron schedule with no firing in the next 1,462
days answers 400 schedule_never_fires.
The router writes the schedule's sentence into schedule.description, such as
Every Monday at 09:00, Europe/London, Every 6 hours from 14 Nov 2026 09:00,
Europe/London or Once, on 20 Nov 2026 at 09:00, Europe/London; a request's
description is ignored. A run starts within five minutes after its time, at an
offset fixed for each task, so tasks set to the same time do not all start in the same second.
next_run_at and a run's scheduled_for carry the time itself.
Cron Dialect
Five fields separated by spaces or tabs: minute, hour, day of month, month, day of week.
| Field | Values | Accepts |
|---|---|---|
| Minute | 0 to 59 | One number only. No *, list, range or step, so a task runs at most once in an hour. |
| Hour | 0 to 23 | *, a value, a range a-b, a list a,b,c, and a step */s or a-b/s |
| Day of month | 1 to 31 | |
| Month | 1 to 12, or JAN to DEC | |
| Day of week | 0 to 7, or SUN to SAT; 0 and 7 are both Sunday |
- Names are the three-letter forms, in any case, and work in ranges and lists:
MON-FRI,jan-mar,Mon,Wed,Fri. - Ranges run from low to high.
SAT-SUNis refused because Sunday is 0; writeSAT,SUNor6-7. - Steps are 1 up to the field's highest value and follow
*or a range. A single value with a step, such as5/2, is refused. - Day matching. A day field that starts with
*is unrestricted. When both day of month and day of week are restricted, a day matches either one:0 9 13 * FRIruns on the 13th and on every Friday. Otherwise a day must match both:0 9 */2 * MONruns on Mondays that fall on odd dates. - Leading zeros are fine:
00 09 * * *is 09:00.
Macros
| Macro | Stands for |
|---|---|
@hourly | 0 * * * * |
@daily, @midnight | 0 0 * * * |
@weekly | 0 0 * * 0 |
@monthly | 0 0 1 * * |
@yearly, @annually | 0 0 1 1 * |
Macros are case-insensitive. Any other macro, @reboot included, is refused.
Refused
- Fewer or more than five fields: no seconds field and no year field.
?,L,Wand#, and full names such asMONDAY.- A value outside its field's range, an empty list item, a range from high to low, and a step of 0 or above the field's highest value.
- An expression over 100 characters, counting any spaces around it.
A refused expression answers 400 invalid_cron with param
schedule.expression and a message that names the field at fault. A schedule
that never fires, or fires twice within an hour, answers the codes in
Schedules.
Examples
| Expression | description, in UTC |
|---|---|
0 9 * * MON | Every Monday at 09:00, UTC |
15 7 * * 1,3,5 | Monday, Wednesday and Friday at 07:15, UTC |
0 9-17 * * MON-FRI | At minute 0 of hours 9-17, Monday to Friday, UTC |
30 */2 * * * | At minute 30 of every 2 hours, UTC |
0 8,12,18 * * SAT,SUN | At minute 0 of hours 8, 12 and 18, Saturday and Sunday, UTC |
0 9 1,15 * * | On days 1 and 15 of the month at 09:00, UTC |
0 9 13 * FRI | On day 13 of the month or every Friday at 09:00, UTC |
0 9 * 1-3 MON | Every Monday at 09:00, in January to March, UTC |
0 9 29 2 * | On day 29 of February at 09:00, UTC |
@hourly | At minute 0 of every hour, UTC |
0 9 29 2 * runs in leap years. 0 9 30 2 * never fires and is refused.
Time Zones and DST
timezone is required: an IANA identifier such as Europe/London, or
UTC, at most 64 characters. Fixed offsets (GMT+5,
Etc/GMT+5, UTC+3, +05:00) and unknown names answer
400 invalid_timezone. Times in a schedule are wall-clock times in that zone;
every other time the API returns is Unix seconds.
| Case | What runs |
|---|---|
| The local time does not exist (clocks go forward) | The same minute after the gap. A daily 01:30 in Europe/London runs at 02:30 BST on 28 Mar 2027; a daily 02:00 in America/New_York runs at 03:00 EDT on 14 Mar 2027. |
| The local time occurs twice (clocks go back) | One run, at the first occurrence. A daily 01:30 in Europe/London runs at 01:30 BST on 25 Oct 2026. An hourly task at minute 30 in America/New_York runs at 01:30 EDT and next at 02:30 EST on 1 Nov 2026, two hours apart. |
| The clocks move 30 minutes | In Australia/Lord_Howe two firings can come 30 minutes apart on the night the clocks go forward: 45 1,2 * * * runs at 01:45 and would run again at 02:45, half an hour later. A firing less than an hour after the task's previous firing is recorded as a skipped run with interval_too_short, and the firing after it runs as usual. The check also applies when a schedule is changed, or a task resumed, soon after a firing. Run now is never held to it. |
An interval in hours | Elapsed time: every 24 hours from 09:00 runs at 08:00 local after the clocks go back. |
An interval in days or weeks | Calendar time: the local time stays put across the change. |
The monthly token cap counts the calendar month in the task's time zone. A task whose stored
time zone stops resolving moves to failed with invalid_schedule.
Tools
tools is a list of MCP tool names a run may call. Left out, the task gets its
kind's default set; an empty list gives a run no tools. A task holds at
most 24 tools, each listed once. GET /v1/scheduled-tasks/tools lists every tool a
task may use and whether this deployment and a workspace offer it.
| Class | Tools |
|---|---|
web | Web search (erebine.research.web_search), Fetch pages (erebine.research.fetch_url), Inspect sites (erebine.research.inspect_site), Image search (erebine.research.image_search), Time (erebine.time.now), Weather (erebine.weather.report) |
workspace | Recall memories (erebine.memory.recall), Search memory (erebine.memory.search), Project brief (erebine.intelligence.brief), Decisions (erebine.intelligence.decisions), Timeline (erebine.intelligence.timeline), Knowledge graph (erebine.intelligence.graph), Plan (erebine.intelligence.trace), Workspace analysis (erebine.intelligence.analyze), List artifacts (erebine.artifact.list), Read artifacts (erebine.artifact.read), Code search (erebine.code.search), Repository overview (erebine.code.repo_overview), Read repositories (erebine.code.repo_read) |
compute | Calculator (erebine.calc.evaluate) |
- Web or workspace, never both. A task that lists a
webtool and aworkspacetool answers400 tool_combination_not_allowed, so a page a run reads cannot steer it into the workspace. The calculator goes with either. Time and weather arewebtools, since each sends a place to a public service: a morning weather briefing listserebine.weather.reporton its own or with other web tools. - No writes and no approvals. Tools that write to the workspace (saving memories, tracking decisions and milestones, linking, creating or updating artifacts), tools that spend credit or store a file on each call (image generation, image fetch), execution tools that reach an EEM and may wait for an approval, plan-board assists, administrative switches, and tools that read or pin another workspace are never offered: listing one answers
400 tool_not_allowed. So does an unknown name. - Offered here. A tool the deployment does not run, or the workspace's tool policy switches off, answers
400 tool_not_availableat create and update. If that changes later, the next run goes without the tool and lists it intools_dropped; when none of a non-empty list can be offered, or a listed tool is no longer allowed unattended, the run fails withtools_unavailableand the task moves tofailed. - API keys. A personal API key schedules only the tools it could call itself: the web tools and the code tools need the
researchscope, the othersinference. A missing scope answers403 scope_insufficientwithparamtools[i]. Run now checks the key again.
Scheduled runs' tool calls have their own per-project rate limit, by default half the limit interactive research has, so a scheduled run does not use up the chat's.
Caps and Billing
A run's tokens are billed to the project like any other request on the task's endpoint. Two caps bound them:
| Cap | Range | Counts |
|---|---|---|
limits.max_tokens_per_run | 10,000 to 2,000,000 (the deployment sets the ceiling) | One run, every attempt and every model round summed |
limits.max_tokens_per_month | The per-run cap to 1,000 times it | Every run of the calendar month in the task's time zone |
Both caps are required when you create a task through the API
(400 missing_required_parameter). The web card, Desktop, erectl and a proposal
fill in the suggested caps from the estimate. A cap out of range answers
400 invalid_limits.
The Estimate
POST /v1/scheduled-tasks/estimate runs every create check on a draft, or on an
edit of a task, writes nothing, and prices it at the endpoint's token rate with the project's
discount:
- Typical tokens per run come from presets until the task has three completed runs: a prompt task with no tools 8,000, with tools 30,000; a research task at
auto80,000, atdeep250,000. After that it is the median of the last ten completed runs, andbasisreadshistory. - Suggested caps. The per-run cap is twice the typical run, rounded up to 10,000 and kept within its range. The monthly cap is that times the runs in the next 31 days (1 for
once), at most 1,000 times the per-run cap. - Warnings.
cap_below_typical: the per-run cap is under a typical run, so runs will stop early.month_below_runs: the monthly cap cannot cover every run in the next 31 days. - Price.
price.chargedisfalsefor a project that is not charged. On a Self-Hosted endpointprice.self_hostedistrueand the figures are the token rate only; hourly EIM charges are not included.
At a Cap
- The per-run cap. A run's cap is its per-run cap or what the month has left, whichever is smaller. Before each model round the run checks that the round, plus room for a closing answer, fits under it. When it does not, the run writes its answer from what it has and ends
completedwithstop_reasontoken_cap. - The monthly cap. When the month has less left than 10,000 tokens or a tenth of the per-run cap, whichever is larger, the firing is skipped with
monthly_cap_reachedand the task pauses with the same reason.resume_atis the start of the next month; the task resumes on its own within an hour of it.
When Credit Runs Out
- Create, resume and run now answer
402 insufficient_quotawhen the project has no credit and402 billing_delinquentwhen a payment is overdue. Listing, reading, pausing, cancelling and deleting still work. - A firing with no credit, or with a payment overdue, is skipped with
credit_exhaustedand the task pauses with the same reason. Settle the balance, then resume it. - A firing whose worst case, its whole token cap, would take the balance under the low-balance floor (the project's own, or the platform's when the project sets none) is skipped with
credit_floor; the task stays active. - A run that runs out of credit stops sending model rounds, answers from what it has with
stop_reasoncredit, and the task pauses withcredit_exhausted. - A token budget on the workspace or endpoint that is spent skips the firing with
budget_exhausted, or stops a run withstop_reasonbudget; the task stays active.
A project that is not charged skips the credit checks. A cancelled run's tokens stay billed.
Where Results Go
The Task's Chat
Creating a task creates its chat, named after the task, in the task's workspace. The chat is
private unless you ask for team; a task scheduled from a chat takes
that chat's visibility. Visibility is the chat's: change it on the chat. A chat that belongs
to a task cannot move to another workspace (409 chat_owned_by_scheduled_task).
Each run that completes or fails is written into the chat as one turn of two rows, a header:
[Scheduled task] Solid-state battery news
Run: Monday 16 November 2026, 09:00 Europe/London
Task:
Solid-state battery announcements from the last week: who shipped, who slipped, with sources.
then the answer. A failed run's answer row is one line saying what failed and, when the task stopped, why. A skipped or cancelled run writes nothing. Delivery waits while a reply is streaming in the chat. If the task's chat was deleted, the next run opens a new one.
Research and the Background Response
- Download research. A run that used the web research tools carries Download research on its answer, and a Deep research run its full report. The run object's
research_bundlesays how many sources and searches it captured. - The background response. Every run is also a stored background response,
response_id, readable with the Responses API from any OpenAI SDK. Itsmetadatacarrieserebine_scheduled_task_idanderebine_scheduled_run_id. - Run records stay for 90 days after a run ends (the deployment sets this); a task's 20 newest runs always stay. Deleting a task deletes its run records; its chat keeps every turn already written.
Notifications and Webhooks
delivery.notify(defaulttrue): when a run endscompletedorfailed, the person the task runs as gets a push on their browsers and iOS devices, Scheduled run finished or Scheduled run failed, naming the task. It never carries the answer. The Scheduled page has Turn on browser notifications.- Email: when a task stops itself, that person gets an email naming the task, why it stopped, and a link to the Scheduled page. A run on its own sends no email.
delivery.webhook(defaultfalse): the task sends the events below to the project's webhook endpoints that subscribe to them.
| Event | Sent when |
|---|---|
scheduled_task.run_completed | A run ended completed. Once per run. |
scheduled_task.run_failed | A run ended failed, after its last attempt. Once per run. |
scheduled_task.paused | The task stopped itself: paused for any reason but a person, or failed. A pause you make sends nothing. |
The events are content-free: no task name, no topic or prompt, no answer. data for a run event:
{
"id": "evt_a1b2c3d4e5f6a7b8c9d0e1f2",
"object": "event",
"type": "scheduled_task.run_completed",
"created_at": 1794820021,
"data": {
"id": "srun_4Rt6Yu8Io0Pa2Sd4Fg6Hj8Kl",
"object": "scheduled_task_run",
"task_id": "stask_8Hq2kL0pVt4Zr9XcN3mB7aWd",
"status": "completed",
"trigger": "schedule",
"scheduled_for": 1794819600,
"started_at": 1794819663,
"finished_at": 1794820021,
"stop_reason": "completed",
"response_id": "resp_68f2a1c9e0b74d5f9a3c2b1d",
"chat_id": "chat_Kp7wE2rY9tU4iO6pA1sD3fG8",
"usage": {"input_tokens": 188422, "output_tokens": 17391, "total_tokens": 205813},
"cost_usd": "0.617439"
}
}
scheduled_task.run_failed carries the same fields plus "error": {"code": "capacity"}, a run error code. data for scheduled_task.paused:
{
"id": "stask_8Hq2kL0pVt4Zr9XcN3mB7aWd",
"object": "scheduled_task",
"state": "paused",
"pause_reason": "monthly_cap_reached",
"resume_at": 1796083200
}
state is paused or failed; resume_at is null unless the task resumes on its own.
Who a Task Runs As
- The project, attributed to a person. A task runs as its project and is attributed to the person who created it (
created_by,attributed_to). Its runs are that person's requests. Only a signed-in session or a personal API key, one that belongs to a user, can use these routes; any other credential answers403 personal_key_required. A personal key needsinferenceto read andworkspaceto change anything, plus each tool's scope. - The person stays. The attributed person must stay an active member who can read the task's chat. If not, the next firing is skipped with
owner_inactiveand the task fails. Leaving the project fails that person's tasks withowner_removed. A project owner who resumes such a task takes it over:attributed_tobecomes the owner. - Who may do what. A task is visible to whoever can read its chat and its workspace; project owners see every task, and a key confined to some workspaces sees only theirs. Anyone who can read a task can pause it and cancel its runs. Changing, deleting, resuming and run now are for the attributed person or a project owner (
403 access_denied). Any project member can create a task in a workspace they can reach. - Chat workspaces that keep content. A zero-retention workspace cannot hold tasks (
400 retention_not_permitted), and neither can an operational (EEM) workspace (400 workspace_not_supported). A workspace that turns zero-retention fails its tasks withzero_retentionand cancels their runs. Deleting a workspace deletes its tasks. - The model.
modelis the slug of one of the project's active chat endpoints (404 model_not_foundotherwise). If the endpoint is deleted or deactivated, the next run fails withendpoint_unavailableand the task stops.
Missed, Overlapping and Failed Runs
- Overlap. A firing that comes while the task's previous run is still queued or running is recorded as a
skippedrun withprevious_run_active. Runs of one task never overlap. - A busy project. A firing waits while two runs of its project are queued or running (the deployment sets this), trying again each minute; after 30 minutes it is skipped with
project_busy. - Catch-up. When a firing could not start within 10 minutes of its time (plus the task's start offset), for example while the router was down, every firing missed since then becomes one run, never one run each. If the latest of them is within 24 hours (the deployment sets this) it runs once as
triggercatch_up; older, it is recorded as askippedrun withmissed.missed_firingscounts the firings it stands for. The next run is the schedule's next time after now. - A run that waits too long. A queued run that has not started 30 minutes after it was due is skipped with
missed. - Retries. An attempt that fails with
interrupted,capacityortimeoutruns again after 5 minutes, then 20, up to three attempts;internalis retried once;endpoint_unavailable,tools_unavailableandrefusednever. A retry happens only while it would start more than 10 minutes before the next firing. Usage adds up across attempts, andattemptsays which one ran last. - Repeated failures. Three scheduled firings in a row that end
failed(the deployment sets this) move the task tofailedwithrepeated_failures. Run now and skipped firings do not count; a completed run starts the count again.
Task States
| State | Meaning |
|---|---|
active | Runs on its schedule; next_run_at is set. |
paused | Stopped and healthy: user (a person paused it), monthly_cap_reached or credit_exhausted. |
failed | Stopped because something a person must fix broke: repeated_failures, owner_removed, owner_inactive, zero_retention, endpoint_unavailable, tools_unavailable or invalid_schedule. |
completed | A once task whose run ended, or whose firing was skipped. |
- Pause stops future runs. A run in progress continues; cancel it to stop it.
- Resume runs every create check again, clears the failure count, and schedules the next run after now. Resuming a
completedtask whose schedule does not fire again answers409 invalid_state: change its schedule first. - Cancel ends a queued run at once. A running run stops at its next model round; the tokens it spent stay billed, and nothing is written to the chat.
- Run now queues a
manualrun in any state, which starts at the scheduler's next pass. While a run of the task is queued or running it answers409 run_active.
Limits
Rows marked deployment are defaults the operator of the deployment can change. The rest are fixed.
| Limit | Value | Set by |
|---|---|---|
Tasks per project, not completed | 50; 3 on a free tier | deployment |
Tasks per person per project, not completed | 20 | deployment |
| Per-run cap ceiling | 2,000,000 tokens | deployment |
| Start offset after each time | Up to 5 minutes | deployment |
| Runs of a project queued or running before a firing waits | 2 | deployment |
| Catch-up window | 24 hours | deployment |
Failed firings in a row before failed | 3 | deployment |
| Run records kept after a run ends | 90 days; the 20 newest per task always | deployment |
| Name, topic, prompt | 120, 2,000 and 8,000 characters | fixed |
| Tools per task | 24 | fixed |
| Per-run cap floor; monthly cap | 10,000 tokens; the per-run cap to 1,000 times it | fixed |
| Time between runs | At least 1 hour | fixed |
once lead time | 60 seconds to 366 days | fixed |
| Cron expression | 100 characters; must fire within 1,462 days | fixed |
| Request body | 256 KiB | fixed |
| List page | 1 to 200, default 50 | fixed |
Idempotency-Key | 1 to 255 printable ASCII characters; binds for 24 hours | fixed |
A create past a task count answers 409 scheduled_task_limit_reached. The routes share the project's management API rate limit; past it they answer 429 rate_limit_exceeded.
API
All paths are relative to your project base URL, https://api.erebine.ai/proj_ABC123.
Send Authorization: Bearer <key> with a personal API key. Bodies and answers
are JSON with snake_case keys and times in Unix seconds. On a task or a run, a field with no
value is null rather than left out; a run's summary is left out of
list items.
| Method | Path | Scope | Result |
|---|---|---|---|
| POST | /:project_id/v1/scheduled-tasks | workspace | 201, the task |
| GET | /:project_id/v1/scheduled-tasks | inference | 200, a page of tasks |
| GET | /:project_id/v1/scheduled-tasks/tools | inference | 200, the tools a task may use |
| POST | /:project_id/v1/scheduled-tasks/estimate | inference | 200, the estimate |
| GET | /:project_id/v1/scheduled-tasks/{task_id} | inference | 200, the task |
| PATCH | /:project_id/v1/scheduled-tasks/{task_id} | workspace | 200, the task |
| DELETE | /:project_id/v1/scheduled-tasks/{task_id} | workspace | 200, {"id", "object", "deleted"} |
| POST | /:project_id/v1/scheduled-tasks/{task_id}/pause | workspace | 200, the task |
| POST | /:project_id/v1/scheduled-tasks/{task_id}/resume | workspace | 200, the task |
| POST | /:project_id/v1/scheduled-tasks/{task_id}/run | workspace | 202, the queued run |
| GET | /:project_id/v1/scheduled-tasks/{task_id}/runs | inference | 200, a page of runs |
| GET | /:project_id/v1/scheduled-tasks/{task_id}/runs/{run_id} | inference | 200, the run |
| POST | /:project_id/v1/scheduled-tasks/{task_id}/runs/{run_id}/cancel | workspace | 200, the run |
Task ids are stask_ and run ids srun_, each followed by 24 letters and digits. Pause and resume are idempotent: pausing a task that is not active, or resuming an active one, returns it unchanged.
Create a Task
| Field | Type | Description |
|---|---|---|
| namerequired | string | 1 to 120 characters after trimming; the chat takes the same name |
| workspace_idrequired | string | The ws_ id of a chat workspace; optional with source, which supplies it |
| modelrequired | string | The slug of an active chat endpoint of the project |
| definitionrequired | object | {"kind": "research", "topic", "depth"} or {"kind": "prompt", "prompt"}; see kinds |
| schedulerequired | object | See Schedules |
| limitsrequired | object | max_tokens_per_run and max_tokens_per_month; see caps |
| toolsoptional | array | MCP tool names; left out, the kind's default set; [], none |
| deliveryoptional | object | notify (default true) and webhook (default false) |
| visibilityoptional | string | The chat's: private (default) or team |
| sourceoptional | object | {"chat_id", "message_id"}: the turn it was scheduled from. The task's workspace must be that chat's, and its visibility defaults to that chat's |
curl -X POST https://api.erebine.ai/proj_ABC123/v1/scheduled-tasks \
-H "Authorization: Bearer ere_my-project_abc123" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: battery-news-1" \
-d '{
"name": "Solid-state battery news",
"workspace_id": "ws_Xn2pQ8rT4vL6mK9jH3gF5dS1",
"model": "qwen3-32b",
"definition": {"kind": "research", "topic": "Solid-state battery announcements from the last week: who shipped, who slipped, with sources.", "depth": "deep"},
"schedule": {"kind": "cron", "expression": "0 9 * * MON", "timezone": "Europe/London"},
"limits": {"max_tokens_per_run": 300000, "max_tokens_per_month": 1500000},
"delivery": {"notify": true, "webhook": false},
"visibility": "private"
}'
The answer is 201 with the task. With an
Idempotency-Key, a repeat of the same body within 24 hours answers the first
task again, with the header Idempotent-Replayed: true; the same key with another
body answers 409 idempotency_key_reused. Keys are per person and project.
List Tasks
Newest first. A list item carries definition.preview, the first 280 characters of the topic or prompt, in place of the text itself; a get carries the text whole.
| Query | Description |
|---|---|
workspace | Only tasks in this workspace (ws_ id) |
state | active, paused, failed or completed |
chat | Only the task that owns this chat (chat_ id); an unknown chat gives an empty page |
limit | 1 to 200, default 50 (400 invalid_limit otherwise) |
after | A page's next_cursor, or a task id (400 invalid_after otherwise) |
{
"object": "list",
"data": [ ... ],
"first_id": "stask_8Hq2kL0pVt4Zr9XcN3mB7aWd",
"last_id": "stask_8Hq2kL0pVt4Zr9XcN3mB7aWd",
"has_more": true,
"next_cursor": "eyJ2IjoxfQ"
}
next_cursor is set only when has_more is true; pass it as after. An empty page has null ids.
Update a Task
PATCH takes any of name, model, definition,
tools, schedule, limits and delivery. A sent
key replaces its whole value, except limits and delivery, which merge
key by key. The result goes through every create check. workspace_id,
visibility and source cannot change
(400 unsupported_parameter), nor can definition.kind. A new
schedule sets the next run from now. A run already in progress keeps the tools and the cap it
started with.
curl -X PATCH https://api.erebine.ai/proj_ABC123/v1/scheduled-tasks/stask_8Hq2kL0pVt4Zr9XcN3mB7aWd \
-H "Authorization: Bearer ere_my-project_abc123" \
-H "Content-Type: application/json" \
-d '{"schedule": {"kind": "cron", "expression": "0 7 * * MON-FRI", "timezone": "Europe/London"}}'
Delete a Task
Deletes the task and its run records, cancelling a run in progress. The chat stays.
{"id": "stask_8Hq2kL0pVt4Zr9XcN3mB7aWd", "object": "scheduled_task", "deleted": true}
Run Now
POST .../{task_id}/run takes no body and answers 202 with the queued
run, trigger manual. Its token cap is the
per-run cap or what the month has left, whichever is smaller. It takes an
Idempotency-Key the way create does.
List Tools
GET .../tools lists every tool a task may use, in the order of the tools table. With ?workspace=ws_..., available also reflects that workspace's tool policy. unavailable_reason is not_mounted or workspace_policy, present only when available is false.
{
"object": "list",
"data": [
{"name": "erebine.research.web_search", "title": "Web search", "class": "web", "available": true, "default_for": ["research"]},
{"name": "erebine.memory.search", "title": "Search memory", "class": "workspace", "available": false, "unavailable_reason": "workspace_policy", "default_for": ["prompt"]}
]
}
Estimate
The body is a create body, where only model and schedule are required
and a missing workspace_id means the project's default workspace; or
{"task_id", "changes"}, where changes is an update body priced
against the task's history. Nothing is written.
{"task_id": "stask_8Hq2kL0pVt4Zr9XcN3mB7aWd", "changes": {"limits": {"max_tokens_per_run": 20000}}}
{
"object": "scheduled_task.estimate",
"schedule": {
"description": "Every Monday at 09:00, Europe/London",
"next_runs": [1794819600, 1795424400, 1796029200],
"runs_per_month": 5
},
"per_run": {"typical_tokens": 250000, "max_tokens": 300000, "typical_cost_usd": "0.750000", "max_cost_usd": "0.900000"},
"per_month": {"typical_tokens": 1250000, "max_tokens": 1500000, "typical_cost_usd": "3.750000", "max_cost_usd": "4.500000"},
"suggested_limits": {"max_tokens_per_run": 500000, "max_tokens_per_month": 2500000},
"basis": "defaults",
"price": {"tier": "base", "usd_per_1m_tokens": "3.000000", "discount": "1.0", "charged": true, "self_hosted": false},
"tools": [{"name": "erebine.research.web_search", "title": "Web search", "class": "web"}],
"destination": {"workspace_id": "ws_Xn2pQ8rT4vL6mK9jH3gF5dS1", "workspace_name": "Research", "visibility": "private"},
"warnings": []
}
runs_per_month counts the firings in the next 31 days. next_runs holds the next three times. Money is a decimal string in USD.
List, Read and Cancel Runs
GET .../runs lists a task's runs newest first, skipped ones included, and takes
status (queued, in_progress, completed,
failed, cancelled or skipped), limit and
after as the task list does. A list item leaves summary out; a get
carries it. POST .../runs/{run_id}/cancel answers the run: a queued run comes back
cancelled; a running one comes back in_progress with
cancel_requested_at set until it stops, or cancelled when its
response had not started. Cancelling a run that has ended answers
409 invalid_state.
The Task Object
{
"id": "stask_8Hq2kL0pVt4Zr9XcN3mB7aWd",
"object": "scheduled_task",
"name": "Solid-state battery news",
"workspace_id": "ws_Xn2pQ8rT4vL6mK9jH3gF5dS1",
"chat_id": "chat_Kp7wE2rY9tU4iO6pA1sD3fG8",
"visibility": "private",
"model": "qwen3-32b",
"definition": {
"kind": "research",
"topic": "Solid-state battery announcements from the last week: who shipped, who slipped, with sources.",
"depth": "deep"
},
"tools": [
"erebine.research.web_search",
"erebine.research.fetch_url",
"erebine.research.inspect_site",
"erebine.calc.evaluate"
],
"schedule": {
"kind": "cron",
"expression": "0 9 * * MON",
"timezone": "Europe/London",
"description": "Every Monday at 09:00, Europe/London"
},
"next_run_at": 1795424400,
"limits": {"max_tokens_per_run": 300000, "max_tokens_per_month": 1500000},
"usage_this_period": {
"period_start": 1793491200,
"period_end": 1796083200,
"runs": 2,
"total_tokens": 412310,
"cost_usd": "1.236930"
},
"delivery": {"notify": true, "webhook": false},
"state": "active",
"pause_reason": null,
"resume_at": null,
"consecutive_failures": 0,
"created_by": {"id": "8f6b1c2e-3d4a-4b5c-9d8e-7f6a5b4c3d2e", "name": "Ann Example"},
"attributed_to": {"id": "8f6b1c2e-3d4a-4b5c-9d8e-7f6a5b4c3d2e", "name": "Ann Example"},
"source": {"chat_id": "chat_Qw3eR5tY7uI9oP1aS2dF4gH6", "message_id": "cmsg_Zx8cV6bN4mL2kJ0hG9fD7sA5"},
"last_run": {
"id": "srun_4Rt6Yu8Io0Pa2Sd4Fg6Hj8Kl",
"status": "completed",
"trigger": "schedule",
"finished_at": 1794820021,
"stop_reason": "completed",
"chat_message_id": "cmsg_Lk9Jh7Gf5Ds3Aq1Ws2Ed4Rf",
"summary_preview": "Two pilot lines moved to volume production; one start-up delayed its sample shipments to Q2."
},
"created_at": 1794565200,
"updated_at": 1794820021
}
| Field | Description |
|---|---|
chat_id | The task's chat. After the chat is deleted it is null until the next run opens a new one, which it then names |
visibility | The chat's: private, team, or select_users when taken from a source chat |
next_run_at | The next time the schedule names; null unless active |
usage_this_period | Runs created this calendar month in the task's time zone, their tokens and their cost |
state, pause_reason, resume_at | See task states; resume_at is set for monthly_cap_reached |
consecutive_failures | Scheduled firings in a row that ended failed |
created_by, attributed_to | {"id", "name"}; null once the user is deleted |
last_run | The newest run that was not skipped, with the first 280 characters of its summary |
The Run Object
{
"id": "srun_4Rt6Yu8Io0Pa2Sd4Fg6Hj8Kl",
"object": "scheduled_task_run",
"task_id": "stask_8Hq2kL0pVt4Zr9XcN3mB7aWd",
"trigger": "schedule",
"scheduled_for": 1794819600,
"status": "completed",
"skip_reason": null,
"attempt": 1,
"missed_firings": 0,
"created_at": 1794819661,
"started_at": 1794819663,
"finished_at": 1794820021,
"response_id": "resp_68f2a1c9e0b74d5f9a3c2b1d",
"chat_id": "chat_Kp7wE2rY9tU4iO6pA1sD3fG8",
"chat_message_id": "cmsg_Lk9Jh7Gf5Ds3Aq1Ws2Ed4Rf",
"delivery": "delivered",
"attributed_to": {"id": "8f6b1c2e-3d4a-4b5c-9d8e-7f6a5b4c3d2e", "name": "Ann Example"},
"model": "qwen3-32b",
"token_cap": 300000,
"usage": {"input_tokens": 188422, "output_tokens": 17391, "total_tokens": 205813},
"cost_usd": "0.617439",
"stop_reason": "completed",
"tools_dropped": [],
"cancel_requested_at": null,
"error": null,
"summary": "Two pilot lines moved to volume production; ...",
"research_bundle": {"available": true, "source_count": 14, "search_count": 6, "bytes": 912004, "partial": false}
}
| Field | Values |
|---|---|
trigger | schedule, catch_up or manual; scheduled_for is null for manual |
status | queued, in_progress, completed, failed, cancelled or skipped |
skip_reason | previous_run_active, missed, credit_exhausted, credit_floor, budget_exhausted, monthly_cap_reached, project_busy, interval_too_short, owner_inactive, zero_retention or workspace_deleted |
stop_reason | completed, token_cap, credit, budget, cancelled, timeout or error |
error | {"code", "message"} for a failed run; code is interrupted, capacity, timeout, endpoint_unavailable, tools_unavailable, refused or internal. The message is the platform's, never model output |
delivery | none (nothing to write), pending, delivered, or not_delivered (the workspace turned zero-retention) |
attempt | 1 to 3; see retries |
missed_firings | For a catch-up, the firings it stands for, itself included |
token_cap | The cap the run ran under |
usage | Every billed call of every attempt summed: input_tokens, output_tokens, total_tokens, and cached_input_tokens, the part of input_tokens the engine served from its prefix cache, present only when the run recorded one. Run events carry the same object |
tools_dropped | Listed tools this run was not offered |
summary | Up to 4,000 characters; left out of a list item |
research_bundle | For a delivered run that captured research: available, source_count, search_count, bytes, partial; otherwise null |
Errors
Errors use the platform's envelope, {"error": {"message", "type", "code", "param"}}, where param is the dotted path of the field at fault, such as schedule.expression or tools[2].
| Status | Code | When |
|---|---|---|
| 400 | missing_required_parameter | A required field is absent |
| 400 | invalid_request | The body is not the expected JSON, a filter or header is malformed, or workspace_id is not the source chat's |
| 400 | invalid_name | The name is over 120 characters |
| 400 | invalid_visibility | visibility is not private or team |
| 400 | invalid_definition | The definition is malformed or too long, or changes kind |
| 400 | invalid_schedule | The schedule is malformed, out of range, or a once time is too soon or too far |
| 400 | invalid_cron | The expression is outside the dialect |
| 400 | invalid_timezone | The time zone is not an IANA identifier or UTC |
| 400 | interval_too_short | Two runs would be less than an hour apart |
| 400 | schedule_never_fires | No firing within 1,462 days |
| 400 | tool_not_allowed | A tool is never offered unattended, unknown, repeated, or past 24 |
| 400 | tool_not_available | The deployment does not run the tool, or the workspace's tool policy switches it off |
| 400 | tool_combination_not_allowed | web and workspace tools in one task |
| 400 | invalid_limits | A cap is out of range |
| 400 | retention_not_permitted | The workspace keeps no content |
| 400 | workspace_not_supported | An operational (EEM) workspace |
| 400 | unsupported_parameter | An update sends workspace_id, visibility or source |
| 400 | invalid_limit | A list's limit is out of range |
| 400 | invalid_after | A list's after is not a cursor or id of that list |
| 402 | insufficient_quota | Create, resume or run now with no credit |
| 402 | billing_delinquent | Create, resume or run now with a payment overdue |
| 403 | personal_key_required | The credential has no person behind it |
| 403 | scope_insufficient | The key lacks the route's scope or a tool's |
| 403 | access_denied | The caller can read the task but may not do this to it |
| 404 | scheduled_task_not_found | No task the caller can read has this id |
| 404 | scheduled_task_run_not_found | No run of this task has this id |
| 404 | workspace_not_found | No workspace the caller can reach has this id |
| 404 | model_not_found | No active chat endpoint of the project has this slug |
| 404 | chat_not_found | The source chat or message is not one the caller can read |
| 409 | run_active | Run now while a run is queued or running |
| 409 | invalid_state | Cancel an ended run, or resume a task whose schedule fires no more |
| 409 | idempotency_key_reused | The same Idempotency-Key with another body |
| 409 | scheduled_task_limit_reached | The project, person or free-tier task count is full |
| 429 | rate_limit_exceeded | The management API rate limit |
| 503 | scheduled_tasks_unavailable | Scheduled tasks are switched off on this deployment; every route answers it, before authentication |
| 503 | database_unavailable | The task store could not be read or written; retry |