Tasks (your AI workforce)

A Task is a standing instruction you give Crevio’s AI: a prompt, an agent, a schedule, and an autonomy level — persisted on your account and run automatically. Where a single API call does one thing once, a Task does it on the trigger you choose (now, on an interval, on a cron schedule, once at a time, or whenever an event fires) and records every execution as a Task Run you can inspect, approve, or feed input into. This is how the agent becomes a workforce instead of a one-shot tool. Tasks have the prefix task_ (object type task); runs have the prefix trun_ (object type task_run).

Tasks consume credits. Every run is one or more AI operations (messages, media generation, web research, calls), all metered pay-per-call. The Task object tracks lifetime spend in total_credits_consumed; each run reports its own credits_consumed. Check your balance with GET /usage.

Anatomy of a Task

POST /v1/tasks accepts these fields (params are top-level — no task wrapper):

string

The task’s display name.

string

An optional human description.

string

required

What you want the agent to do — the instruction it runs every time.

enum

required

One of immediate, cron, interval, once, event. See below.

enum

business (default) or engineering. Business operates your account through the API; engineering writes and ships code on a Site.

enum

autonomous, supervised, or read_only. Controls how much human oversight each run requires.

array

Where results are delivered: any of notification, email, telegram, discord, slack.

object

For event triggers: filters that must match the incoming event for the task to fire. See Events.

string

The Site (site_...) the task works on. Its repo is mounted as the agent’s workspace. Defaults to your account’s default site. Most relevant for the engineering agent.

string

Override the model used for the run.

string

Cron schedule (for trigger_type: cron).

integer

Seconds between runs (for trigger_type: interval).

date-time

When to run (for trigger_type: once).

string

Timezone for cron/scheduled_at, e.g. America/New_York.

date-time

After this time the task stops running.

boolean

Whether the task is enabled. Set false to pause without deleting.

A created Task also returns scheduling and accounting state: next_run_at, last_run_at, total_runs_count, consecutive_failure_count, and total_credits_consumed.

Choosing an agent

Agent	What it does	When to use it
`business` (default)	Operates your business through the API: products, checkouts, customers, email, socials, web research, calls.	Marketing, ops, sales, reporting, follow-ups.
`engineering`	Writes and ships code on a Site — the repo is mounted as its workspace; it can build and deploy. Scope it with `site_id`.	Website changes, bug fixes, new features, deploys.

Triggers

trigger_type decides when a task runs. There are five, each with its own scheduling field.

`immediate` — run once, right now

Fires a single run the moment you create the task. Good for kicking off ad-hoc work asynchronously.

curl -X POST https://api.crevio.co/v1/tasks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Draft launch tweets",
    "prompt": "Write 5 launch tweets for my new pottery course and save them as social drafts.",
    "trigger_type": "immediate",
    "agent": "business",
    "approval_mode": "supervised",
    "delivery_methods": ["notification"]
  }'

`cron` — run on a cron schedule

Recurring, calendar-based. Pair cron_expression with a timezone.

curl -X POST https://api.crevio.co/v1/tasks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monday sales digest",
    "prompt": "Summarize last week’s orders, revenue, refunds, and top 5 products. Email me the report.",
    "trigger_type": "cron",
    "cron_expression": "0 9 * * MON",
    "timezone": "America/New_York",
    "agent": "business",
    "approval_mode": "autonomous",
    "delivery_methods": ["email", "notification"]
  }'

`interval` — run every N seconds

Fixed cadence, independent of the wall clock. Set interval_seconds.

curl -X POST https://api.crevio.co/v1/tasks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hourly inbox triage",
    "prompt": "Check new customer emails, label them, and draft replies to anything urgent.",
    "trigger_type": "interval",
    "interval_seconds": 3600,
    "agent": "business",
    "approval_mode": "supervised",
    "delivery_methods": ["slack"]
  }'

`once` — run a single time at a future moment

Schedule a one-off with scheduled_at.

curl -X POST https://api.crevio.co/v1/tasks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday price drop",
    "prompt": "Apply the BLACKFRIDAY discount to all active courses and announce it on social.",
    "trigger_type": "once",
    "scheduled_at": "2026-11-27T13:00:00Z",
    "timezone": "America/New_York",
    "agent": "business",
    "approval_mode": "autonomous",
    "delivery_methods": ["notification"]
  }'

`event` — run when something happens

The task lies dormant until a matching event fires (e.g. order.paid). Constrain which events trigger it with event_conditions.

curl -X POST https://api.crevio.co/v1/tasks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome new buyers",
    "prompt": "When an order is paid, send the buyer a personalized welcome email and add them to the onboarding sequence.",
    "trigger_type": "event",
    "event_conditions": { "event": "order.paid" },
    "agent": "business",
    "approval_mode": "autonomous",
    "delivery_methods": ["notification"]
  }'

See the Events guide for the full list of subscribable events and how event_conditions works.

Autonomy: `approval_mode`

approval_mode is the human-in-the-loop dial. It decides whether a run can act on its own, must pause for your approval, or can only observe.

Mode	Behavior
`autonomous`	The agent runs end-to-end and takes actions (writes, sends, deploys) without asking. Best for trusted, well-scoped tasks.
`supervised`	The agent pauses at decisions that require approval. The run enters a needs-input state and waits for you to approve, deny, or provide input before continuing.
`read_only`	The agent can read and analyze but cannot make changes. Best for reporting, audits, and research.

The supervised loop

A supervised run pauses instead of acting, which fires the task_run.needs_input webhook event (and notifies you via your delivery_methods). You review it in the Crevio dashboard — approving the pending action or giving the agent direction — and it resumes from where it stopped. The cycle:

Run starts and reaches a checkpoint

The agent does its work until it hits an action that needs approval (or it needs information from you).

Run pauses in needs_input

The Task Run status becomes needs_input; task_run.needs_input fires and you’re notified.

You review and respond in the dashboard

Approve the pending action or give the agent more direction from the Crevio dashboard or notification. (Over the API you can read run state and update its status/summary — see below.)

Run resumes

The agent continues from the checkpoint and completes (or pauses again at the next one).

Task Runs

Each execution of a Task is a Task Run (trun_, object type task_run). Runs are read-mostly: you list and get them to inspect what happened, and PATCH them to update their status/summary.

The run object

Field	Description
`task_id`	The parent task (`task_...`).
`status`	Lifecycle state (e.g. running, needs-input, completed, failed).
`summary`	The agent’s natural-language summary of what it did.
`error_message`	Populated when the run failed.
`input_tokens` / `output_tokens`	Token usage for the run.
`credits_consumed`	Credits this run cost.
`tool_calls_count`	How many API/tool calls the agent made.
`duration_ms`	Wall-clock duration.
`started_at` / `completed_at`	Timestamps.

List and get runs

cURL
MCP (agent)

# List recent runs (optionally filter by task)
curl https://api.crevio.co/v1/task_runs \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Get one run
curl https://api.crevio.co/v1/task_runs/trun_abc123 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Inside api_execute
runs = get("/task_runs")["data"]
runs.select { |r| r["status"] == "needs_input" }
    .map { |r| { id: r["id"], summary: r["summary"] } }

List responses use the standard envelope: { "object": "list", "data": [...], "has_more": bool }.

Updating a run’s state

PATCH /v1/task_runs/{id} updates a run’s state. The body accepts:

enum

pending, running, completed, failed, or needs_input.

string | null

The run’s summary text.

string | null

An error message for a failed run.

integer

Recorded input token count.

integer

Recorded output token count.

For a run paused in needs_input, you resume or close it out by PATCHing status (and optionally summary/error_message) — for example set status to running to release it, or to completed/failed to close it.

curl -X PATCH https://api.crevio.co/v1/task_runs/trun_abc123 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "summary": "Reviewed and approved — sent the broadcast to paid customers."
  }'

The API lets you read run state and update status/summary — there is no field for sending free-form instructions back to the agent. The interactive back-and-forth for a supervised run (approving a pending action or giving the agent more direction in plain English) happens in the Crevio dashboard and notifications, not over the API.

Don’t poll for paused runs — subscribe to the task_run.needs_input, task_run.completed, and task_run.failed webhook events and react as they arrive.

Managing tasks

# Pause a task without deleting it
curl -X PATCH https://api.crevio.co/v1/tasks/task_abc123 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

# Delete a task
curl -X DELETE https://api.crevio.co/v1/tasks/task_abc123 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

A delete returns { "id": "task_abc123", "object": "task", "deleted": true }.

Limits

Every value below is also returned live by GET /v1/status under limits, so you can read the current numbers rather than hard-coding these.

Concurrency

	Limit	What happens past it
Active runs per task	1	A second start (scheduled, `run_now`, or a test run) is refused while one is in flight. The next scheduled tick retries.
Active runs per account	5	Further runs are deferred, not dropped — the dispatcher re-considers them on its next tick, and manual starts return `422`.

“Active” means pending, running, or needs_input — a run parked on an approval still occupies its slot, so resolve or cancel it to free capacity.

Runtime

	Limit
Maximum run duration	4 hours, after which the run ends as `timed_out`
`condition_script`	15s, 10,000 characters
`pre_run_script`	30s, 10,000 characters
Task `prompt`	10,000 characters
Dependencies (`depends_on`)	10 tasks

A turn itself is deliberately uncapped below that 4-hour ceiling — a site build can legitimately run for a long time. The ceiling exists so a wedged run can’t spin forever, and it is reported as timed_out rather than failed so you can tell “it never finished” from “it broke”.

Truncation

Values a run produces are bounded before they reach the model, so a large result is trimmed rather than rejected:

	Limit
`execute` / script return value and logs	~10,000 tokens each
Triggering event payload in run context	8,000 characters
Run `summary`	500 characters
`error_message`	1,000 characters

Next steps

Events & Event Sources

Fire event-Tasks from internal events and third-party apps.

AI & Agents overview

How Tasks fit into Crevio’s broader agentic model.

Webhooks

Get notified when runs complete, fail, or need your input.

Usage & credits

See how task runs are metered and check your balance.

Getting started

AI & agents

Core concepts

Integrations

Recipes

Tasks (your AI workforce)

Anatomy of a Task

Choosing an agent

Triggers

`immediate` — run once, right now

`cron` — run on a cron schedule

`interval` — run every N seconds

`once` — run a single time at a future moment

`event` — run when something happens

Autonomy: `approval_mode`

The supervised loop

Task Runs

The run object

List and get runs

Updating a run’s state

Managing tasks

Limits

Concurrency

Runtime

Truncation

Next steps

Events & Event Sources

AI & Agents overview

Webhooks

Usage & credits

​Anatomy of a Task

​Choosing an agent

​Triggers

​immediate — run once, right now

​cron — run on a cron schedule

​interval — run every N seconds

​once — run a single time at a future moment

​event — run when something happens

​Autonomy: approval_mode

​The supervised loop

​Task Runs

​The run object

​List and get runs

​Updating a run’s state

​Managing tasks

​Limits

​Concurrency

​Runtime

​Truncation

​Next steps

Events & Event Sources

AI & Agents overview

Webhooks

Usage & credits

Anatomy of a Task

Choosing an agent

Triggers

`immediate` — run once, right now

`cron` — run on a cron schedule

`interval` — run every N seconds

`once` — run a single time at a future moment

`event` — run when something happens

Autonomy: `approval_mode`

The supervised loop

Task Runs

The run object

List and get runs

Updating a run’s state

Managing tasks

Limits

Concurrency

Runtime

Truncation

Next steps