> ## Documentation Index
> Fetch the complete documentation index at: https://crevio.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tasks (your AI workforce)

> Tasks turn Crevio's AI into an autonomous workforce — standing instructions that run on a schedule or event, with the autonomy level you choose. Learn triggers, agents, approval modes, delivery, and how to respond to supervised runs.

**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`).

<Note>
  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`](/developer/guides/api-overview).
</Note>

## Anatomy of a Task

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

<ParamField body="name" type="string">The task's display name.</ParamField>
<ParamField body="description" type="string">An optional human description.</ParamField>
<ParamField body="prompt" type="string" required>What you want the agent to do — the instruction it runs every time.</ParamField>
<ParamField body="trigger_type" type="enum" required>One of `immediate`, `cron`, `interval`, `once`, `event`. See below.</ParamField>
<ParamField body="agent" type="enum">`business` (default) or `engineering`. Business operates your account through the API; engineering writes and ships code on a Site.</ParamField>
<ParamField body="approval_mode" type="enum">`autonomous`, `supervised`, or `read_only`. Controls how much human oversight each run requires.</ParamField>
<ParamField body="delivery_methods" type="array">Where results are delivered: any of `notification`, `email`, `telegram`, `discord`, `slack`.</ParamField>
<ParamField body="event_conditions" type="object">For `event` triggers: filters that must match the incoming event for the task to fire. See [Events](/developer/guides/events).</ParamField>
<ParamField body="site_id" type="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.</ParamField>
<ParamField body="model_id" type="string">Override the model used for the run.</ParamField>
<ParamField body="cron_expression" type="string">Cron schedule (for `trigger_type: cron`).</ParamField>
<ParamField body="interval_seconds" type="integer">Seconds between runs (for `trigger_type: interval`).</ParamField>
<ParamField body="scheduled_at" type="date-time">When to run (for `trigger_type: once`).</ParamField>
<ParamField body="timezone" type="string">Timezone for `cron`/`scheduled_at`, e.g. `America/New_York`.</ParamField>
<ParamField body="expires_at" type="date-time">After this time the task stops running.</ParamField>
<ParamField body="active" type="boolean">Whether the task is enabled. Set `false` to pause without deleting.</ParamField>

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.

```bash theme={null}
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`.

```bash theme={null}
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`.

```bash theme={null}
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`.

```bash theme={null}
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`.

```bash theme={null}
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](/developer/guides/events) 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](/developer/guides/webhooks) (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:

<Steps>
  <Step title="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).
  </Step>

  <Step title="Run pauses in needs_input">
    The Task Run status becomes `needs_input`; `task_run.needs_input` fires and you're notified.
  </Step>

  <Step title="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.)
  </Step>

  <Step title="Run resumes">
    The agent continues from the checkpoint and completes (or pauses again at the next one).
  </Step>
</Steps>

## 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

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    # 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"
    ```
  </Tab>

  <Tab title="MCP (agent)">
    ```ruby theme={null}
    # Inside code_execute
    runs = get("/task_runs")["data"]
    runs.select { |r| r["status"] == "needs_input" }
        .map { |r| { id: r["id"], summary: r["summary"] } }
    ```
  </Tab>
</Tabs>

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:

<ParamField body="status" type="enum">`pending`, `running`, `completed`, `failed`, or `needs_input`.</ParamField>
<ParamField body="summary" type="string | null">The run's summary text.</ParamField>
<ParamField body="error_message" type="string | null">An error message for a failed run.</ParamField>
<ParamField body="input_tokens" type="integer">Recorded input token count.</ParamField>
<ParamField body="output_tokens" type="integer">Recorded output token count.</ParamField>

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.

```bash theme={null}
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."
  }'
```

<Note>
  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.
</Note>

<Tip>
  Don't poll for paused runs — subscribe to the `task_run.needs_input`, `task_run.completed`, and `task_run.failed` [webhook events](/developer/guides/webhooks) and react as they arrive.
</Tip>

## Managing tasks

```bash theme={null}
# 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 }`.

## Next steps

<CardGroup cols={2}>
  <Card title="Events & Event Sources" icon="bolt" href="/developer/guides/events">
    Fire event-Tasks from internal events and third-party apps.
  </Card>

  <Card title="AI & Agents overview" icon="robot" href="/developer/guides/agents-overview">
    How Tasks fit into Crevio's broader agentic model.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/developer/guides/webhooks">
    Get notified when runs complete, fail, or need your input.
  </Card>

  <Card title="Usage & credits" icon="credit-card" href="/developer/guides/api-overview">
    See how task runs are metered and check your balance.
  </Card>
</CardGroup>