Scheduled Tasks API
Schedule Ask Goliath to run an instruction on a cron or at a set time, and pause, resume, edit or delete scheduled tasks through the Goliath developer API
About
A scheduled task runs Ask Goliath on a schedule
as its owner: every run is told the task’s instruction and reports back in
the task’s own chat. Use these operations to create recurring or one-off
tasks, list everything scheduled in your organization, and pause, resume,
edit or delete a task.
All operations go through the developer API gateway — one endpoint, called by
operationId. If you haven’t set up a key yet, start with the
Developer API Overview.
Operations
Reading tasks (READ scope)
| operationId | What it does |
|---|---|
listScheduledTasks |
Every scheduled task in the organization — yours first, then teammates’, newest first: title, status (ACTIVE, PAUSED, PAUSED_ERRORS after repeated failures, EXHAUSTED when finished), cadence (ONE_OFF or RECURRING), the schedule in words, nextRunAt, lastRunAt, runCount, owner, tags, and canEdit. Narrow by ownerUserId, tag, statuses or cadence. |
getScheduledTask |
One task by taskId: its instruction, cronExpression and timezone (a one-off has oneOffAt), abilities, expiresAt, notifyOnlyOnChange, its chat (sessionId), and whether it is running now. |
Managing tasks (WRITE scope)
| operationId | What it does |
|---|---|
createScheduledTask |
Schedule an instruction under a title, run as the key owner. Give exactly one of cronExpression (recurring, standard 5-field cron) or fireAt (once), read in timezone (IANA). Optional expiresAt ends it. Refused while scheduled tasks are switched off for the workspace. |
updateScheduledTask |
Change a task’s title, instruction, timing ({ cronExpression or fireAt, timezone }, exactly one of the two), tags, expiresAt or notifyOnlyOnChange (only report when something changed). Only what you send changes; clearExpiresAt: true removes the end and is not sent with expiresAt. |
pauseScheduledTask |
Pause a task until it is resumed. |
resumeScheduledTask |
Resume a paused task from its next occurrence. Missed runs are not made up. |
deleteScheduledTask |
Delete a task for good; its chat stays. Pause it instead to stop it for now. |
Only a task’s owner or an organization admin may change it — canEdit on
listScheduledTasks says which tasks the key owner can. A task created
through the API holds no abilities: each run asks its owner before taking
any action.
Example
Every weekday at 8:00 in New York, summarize yesterday’s new leads:
curl -X POST https://server.goliathdata.com/api/v1/call \
-H "Authorization: Bearer gsk_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c2b8e-0d55-4a1e-9b8c-5a2e3f7d9c10" \
-d '{ "operationId": "createScheduledTask", "variables": { "title": "Morning lead summary", "instruction": "Summarize the leads that came in yesterday and flag any with no owner.", "cronExpression": "0 8 * * 1-5", "timezone": "America/New_York" } }'Full variable schemas, response shapes, and worked examples for every operation are available from the discovery endpoint.