docs
// Features

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

KindDefinitionWhat a run doesTools 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, deep when the reply ran Deep research and auto otherwise, 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-tasks creates, prices and manages tasks from a terminal.
  • The API. POST /v1/scheduled-tasks, after POST /v1/scheduled-tasks/estimate to 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.

KindFieldsRules
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.
JSON
{"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.

FieldValuesAccepts
Minute0 to 59One number only. No *, list, range or step, so a task runs at most once in an hour.
Hour0 to 23*, a value, a range a-b, a list a,b,c, and a step */s or a-b/s
Day of month1 to 31
Month1 to 12, or JAN to DEC
Day of week0 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-SUN is refused because Sunday is 0; write SAT,SUN or 6-7.
  • Steps are 1 up to the field's highest value and follow * or a range. A single value with a step, such as 5/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 * FRI runs on the 13th and on every Friday. Otherwise a day must match both: 0 9 */2 * MON runs on Mondays that fall on odd dates.
  • Leading zeros are fine: 00 09 * * * is 09:00.

Macros

MacroStands for
@hourly0 * * * *
@daily, @midnight0 0 * * *
@weekly0 0 * * 0
@monthly0 0 1 * *
@yearly, @annually0 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, W and #, and full names such as MONDAY.
  • 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

Expressiondescription, in UTC
0 9 * * MONEvery Monday at 09:00, UTC
15 7 * * 1,3,5Monday, Wednesday and Friday at 07:15, UTC
0 9-17 * * MON-FRIAt 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,SUNAt 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 * FRIOn day 13 of the month or every Friday at 09:00, UTC
0 9 * 1-3 MONEvery Monday at 09:00, in January to March, UTC
0 9 29 2 *On day 29 of February at 09:00, UTC
@hourlyAt 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.

CaseWhat 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 minutesIn 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 hoursElapsed time: every 24 hours from 09:00 runs at 08:00 local after the clocks go back.
An interval in days or weeksCalendar 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.

ClassTools
webWeb 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)
workspaceRecall 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)
computeCalculator (erebine.calc.evaluate)
  • Web or workspace, never both. A task that lists a web tool and a workspace tool answers 400 tool_combination_not_allowed, so a page a run reads cannot steer it into the workspace. The calculator goes with either. Time and weather are web tools, since each sends a place to a public service: a morning weather briefing lists erebine.weather.report on 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_available at create and update. If that changes later, the next run goes without the tool and lists it in tools_dropped; when none of a non-empty list can be offered, or a listed tool is no longer allowed unattended, the run fails with tools_unavailable and the task moves to failed.
  • API keys. A personal API key schedules only the tools it could call itself: the web tools and the code tools need the research scope, the others inference. A missing scope answers 403 scope_insufficient with param tools[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:

CapRangeCounts
limits.max_tokens_per_run10,000 to 2,000,000 (the deployment sets the ceiling)One run, every attempt and every model round summed
limits.max_tokens_per_monthThe per-run cap to 1,000 times itEvery 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 auto 80,000, at deep 250,000. After that it is the median of the last ten completed runs, and basis reads history.
  • 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.charged is false for a project that is not charged. On a Self-Hosted endpoint price.self_hosted is true and 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 completed with stop_reason token_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_reached and the task pauses with the same reason. resume_at is 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_quota when the project has no credit and 402 billing_delinquent when 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_exhausted and 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_reason credit, and the task pauses with credit_exhausted.
  • A token budget on the workspace or endpoint that is spent skips the firing with budget_exhausted, or stops a run with stop_reason budget; 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:

text
[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_bundle says 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. Its metadata carries erebine_scheduled_task_id and erebine_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 (default true): when a run ends completed or failed, 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 (default false): the task sends the events below to the project's webhook endpoints that subscribe to them.
EventSent when
scheduled_task.run_completedA run ended completed. Once per run.
scheduled_task.run_failedA run ended failed, after its last attempt. Once per run.
scheduled_task.pausedThe 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:

JSON
{ "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:

JSON
{ "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 answers 403 personal_key_required. A personal key needs inference to read and workspace to 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_inactive and the task fails. Leaving the project fails that person's tasks with owner_removed. A project owner who resumes such a task takes it over: attributed_to becomes 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 with zero_retention and cancels their runs. Deleting a workspace deletes its tasks.
  • The model. model is the slug of one of the project's active chat endpoints (404 model_not_found otherwise). If the endpoint is deleted or deactivated, the next run fails with endpoint_unavailable and 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 skipped run with previous_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 trigger catch_up; older, it is recorded as a skipped run with missed. missed_firings counts 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, capacity or timeout runs again after 5 minutes, then 20, up to three attempts; internal is retried once; endpoint_unavailable, tools_unavailable and refused never. A retry happens only while it would start more than 10 minutes before the next firing. Usage adds up across attempts, and attempt says which one ran last.
  • Repeated failures. Three scheduled firings in a row that end failed (the deployment sets this) move the task to failed with repeated_failures. Run now and skipped firings do not count; a completed run starts the count again.

Task States

StateMeaning
activeRuns on its schedule; next_run_at is set.
pausedStopped and healthy: user (a person paused it), monthly_cap_reached or credit_exhausted.
failedStopped because something a person must fix broke: repeated_failures, owner_removed, owner_inactive, zero_retention, endpoint_unavailable, tools_unavailable or invalid_schedule.
completedA 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 completed task whose schedule does not fire again answers 409 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 manual run in any state, which starts at the scheduler's next pass. While a run of the task is queued or running it answers 409 run_active.

Limits

Rows marked deployment are defaults the operator of the deployment can change. The rest are fixed.

LimitValueSet by
Tasks per project, not completed50; 3 on a free tierdeployment
Tasks per person per project, not completed20deployment
Per-run cap ceiling2,000,000 tokensdeployment
Start offset after each timeUp to 5 minutesdeployment
Runs of a project queued or running before a firing waits2deployment
Catch-up window24 hoursdeployment
Failed firings in a row before failed3deployment
Run records kept after a run ends90 days; the 20 newest per task alwaysdeployment
Name, topic, prompt120, 2,000 and 8,000 charactersfixed
Tools per task24fixed
Per-run cap floor; monthly cap10,000 tokens; the per-run cap to 1,000 times itfixed
Time between runsAt least 1 hourfixed
once lead time60 seconds to 366 daysfixed
Cron expression100 characters; must fire within 1,462 daysfixed
Request body256 KiBfixed
List page1 to 200, default 50fixed
Idempotency-Key1 to 255 printable ASCII characters; binds for 24 hoursfixed

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.

MethodPathScopeResult
POST/:project_id/v1/scheduled-tasksworkspace201, the task
GET/:project_id/v1/scheduled-tasksinference200, a page of tasks
GET/:project_id/v1/scheduled-tasks/toolsinference200, the tools a task may use
POST/:project_id/v1/scheduled-tasks/estimateinference200, the estimate
GET/:project_id/v1/scheduled-tasks/{task_id}inference200, the task
PATCH/:project_id/v1/scheduled-tasks/{task_id}workspace200, the task
DELETE/:project_id/v1/scheduled-tasks/{task_id}workspace200, {"id", "object", "deleted"}
POST/:project_id/v1/scheduled-tasks/{task_id}/pauseworkspace200, the task
POST/:project_id/v1/scheduled-tasks/{task_id}/resumeworkspace200, the task
POST/:project_id/v1/scheduled-tasks/{task_id}/runworkspace202, the queued run
GET/:project_id/v1/scheduled-tasks/{task_id}/runsinference200, a page of runs
GET/:project_id/v1/scheduled-tasks/{task_id}/runs/{run_id}inference200, the run
POST/:project_id/v1/scheduled-tasks/{task_id}/runs/{run_id}/cancelworkspace200, 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

FieldTypeDescription
namerequiredstring1 to 120 characters after trimming; the chat takes the same name
workspace_idrequiredstringThe ws_ id of a chat workspace; optional with source, which supplies it
modelrequiredstringThe slug of an active chat endpoint of the project
definitionrequiredobject{"kind": "research", "topic", "depth"} or {"kind": "prompt", "prompt"}; see kinds
schedulerequiredobjectSee Schedules
limitsrequiredobjectmax_tokens_per_run and max_tokens_per_month; see caps
toolsoptionalarrayMCP tool names; left out, the kind's default set; [], none
deliveryoptionalobjectnotify (default true) and webhook (default false)
visibilityoptionalstringThe chat's: private (default) or team
sourceoptionalobject{"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
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.

QueryDescription
workspaceOnly tasks in this workspace (ws_ id)
stateactive, paused, failed or completed
chatOnly the task that owns this chat (chat_ id); an unknown chat gives an empty page
limit1 to 200, default 50 (400 invalid_limit otherwise)
afterA page's next_cursor, or a task id (400 invalid_after otherwise)
JSON
{ "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
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.

JSON
{"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.

JSON
{ "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.

JSON
{"task_id": "stask_8Hq2kL0pVt4Zr9XcN3mB7aWd", "changes": {"limits": {"max_tokens_per_run": 20000}}}
JSON
{ "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

JSON
{ "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 }
FieldDescription
chat_idThe task's chat. After the chat is deleted it is null until the next run opens a new one, which it then names
visibilityThe chat's: private, team, or select_users when taken from a source chat
next_run_atThe next time the schedule names; null unless active
usage_this_periodRuns created this calendar month in the task's time zone, their tokens and their cost
state, pause_reason, resume_atSee task states; resume_at is set for monthly_cap_reached
consecutive_failuresScheduled firings in a row that ended failed
created_by, attributed_to{"id", "name"}; null once the user is deleted
last_runThe newest run that was not skipped, with the first 280 characters of its summary

The Run Object

JSON
{ "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} }
FieldValues
triggerschedule, catch_up or manual; scheduled_for is null for manual
statusqueued, in_progress, completed, failed, cancelled or skipped
skip_reasonprevious_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_reasoncompleted, 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
deliverynone (nothing to write), pending, delivered, or not_delivered (the workspace turned zero-retention)
attempt1 to 3; see retries
missed_firingsFor a catch-up, the firings it stands for, itself included
token_capThe cap the run ran under
usageEvery 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_droppedListed tools this run was not offered
summaryUp to 4,000 characters; left out of a list item
research_bundleFor 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].

StatusCodeWhen
400missing_required_parameterA required field is absent
400invalid_requestThe body is not the expected JSON, a filter or header is malformed, or workspace_id is not the source chat's
400invalid_nameThe name is over 120 characters
400invalid_visibilityvisibility is not private or team
400invalid_definitionThe definition is malformed or too long, or changes kind
400invalid_scheduleThe schedule is malformed, out of range, or a once time is too soon or too far
400invalid_cronThe expression is outside the dialect
400invalid_timezoneThe time zone is not an IANA identifier or UTC
400interval_too_shortTwo runs would be less than an hour apart
400schedule_never_firesNo firing within 1,462 days
400tool_not_allowedA tool is never offered unattended, unknown, repeated, or past 24
400tool_not_availableThe deployment does not run the tool, or the workspace's tool policy switches it off
400tool_combination_not_allowedweb and workspace tools in one task
400invalid_limitsA cap is out of range
400retention_not_permittedThe workspace keeps no content
400workspace_not_supportedAn operational (EEM) workspace
400unsupported_parameterAn update sends workspace_id, visibility or source
400invalid_limitA list's limit is out of range
400invalid_afterA list's after is not a cursor or id of that list
402insufficient_quotaCreate, resume or run now with no credit
402billing_delinquentCreate, resume or run now with a payment overdue
403personal_key_requiredThe credential has no person behind it
403scope_insufficientThe key lacks the route's scope or a tool's
403access_deniedThe caller can read the task but may not do this to it
404scheduled_task_not_foundNo task the caller can read has this id
404scheduled_task_run_not_foundNo run of this task has this id
404workspace_not_foundNo workspace the caller can reach has this id
404model_not_foundNo active chat endpoint of the project has this slug
404chat_not_foundThe source chat or message is not one the caller can read
409run_activeRun now while a run is queued or running
409invalid_stateCancel an ended run, or resume a task whose schedule fires no more
409idempotency_key_reusedThe same Idempotency-Key with another body
409scheduled_task_limit_reachedThe project, person or free-tier task count is full
429rate_limit_exceededThe management API rate limit
503scheduled_tasks_unavailableScheduled tasks are switched off on this deployment; every route answers it, before authentication
503database_unavailableThe task store could not be read or written; retry