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

# Tasks and automation

> Create communication, Computer, retry, repeating, and one-off Tasks with verifiable outcomes.

Vida Tasks represent concrete work. Use `targetAccountId` to scope the request and `accountId` to identify the Agent that owns the created Task. These IDs normally match.

## Choose the Task type

| Type                    | Use it for                                                        |
| ----------------------- | ----------------------------------------------------------------- |
| `call`, `text`, `email` | One communication attempt or one retry-managed communication goal |
| `computer`              | One bounded Computer Agent assignment now or at `scheduledFor`    |
| `repeating`             | Computer Agent work on a cron or fixed interval                   |
| `cronOneOff`            | Computer Agent work once at a specified time                      |

Read `GET /api/v2/tasks/limits` before creating communication work.

### Optional outbound number pools

Outbound call and text Tasks can use a managed pool of assigned numbers when an approved workflow
needs number rotation at scale. This is an optional capability that Vida must enable and configure
for the organization; it is not a public self-service pool-management API. Contact Vida to review
the use case and enable it. Afterward, verify the numbers assigned to the Agent with
`GET /api/v2/phoneNumbers?targetAccountId=...` and test representative Tasks before increasing
volume.

## Create one communication goal

Use one retry-enabled Task for one logical outcome. `goal.completionCriteria` defines success; `retryPolicy` defines which unresolved outcomes should try again and when.

Do not create one Task per attempt. Inspect `attemptHistory`, `result`, `logsRef`, and per-attempt conversation references on the original Task.

`externalTaskId` is correlation data, not an idempotency key. Reconcile existing Tasks before retrying an uncertain create request.

## Assign Computer work

Create `type:"computer"` with a provisioned Computer Agent `accountId` and complete `taskContext`. Vida creates a dedicated linked chat for the work. Poll the Task to a terminal state, then inspect its `chatRef` or room messages for the work, tool calls, and final result.

Canceling stops active work when possible. Deleting a Computer Task also stops active work before removing the Task record.

## Create recurring or one-off work

Create a `repeating` or `cronOneOff` Task with a nonblank `title`, `taskContext`, and `cronSchedule`. Use five-field cron expressions, fixed intervals of at least one minute, or an `at` schedule for one-off work.

Create recurring work paused when it must be reviewed before activation. Run a controlled test with `/tasks/{taskId}/run`, then inspect `/tasks/{taskId}/runs`. An accepted run is not proof of completion.

Inspect the returned run's `chatRef` for the Agent's complete work and tool calls. Reconcile the
destination effect before forcing another run after any timeout or uncertain result; do not infer
that an empty or delayed history response means no work started.

Repeating and one-off Task updates accept the documented title, task context, state, and timing fields. Delete the Task to remove its future execution. Do not send undocumented metadata or server-generated identifiers.

## Design proactive polling safely

A common Computer Agent pattern is poll, qualify, deduplicate, fan out bounded work, and write back
only confirmed outcomes. Treat it as one explicit workflow:

1. Define the source query, timezone, maximum items per run, and what qualifies an item.
2. Preserve the source system's opaque IDs exactly and define a durable deduplication key.
3. Bound downstream Task creation by current capacity and reconcile existing Tasks before creating
   more work.
4. Make writeback ambiguity-safe: update the source only after the destination outcome is confirmed,
   and never blindly retry a write whose result is uncertain.
5. Create the repeating Task paused, force one controlled run, inspect its linked chat, Tasks, and
   destination effects, then activate it deliberately.

Every proactive Agent design should answer two separate questions: what triggers the work, and what
evidence proves one run completed correctly?

## Use batches intentionally

Batch only eligible Tasks after reconciling active and prior work. Save the returned `batchId`; asynchronous batches must be polled to a terminal state and inspected for inserted, rejected, and failed rows.

After a timeout, conflict, or server error, query by stable correlation fields before resubmitting. A partial synchronous batch may already have created earlier items.

<Note>
  For complete retry policy rules and ready-to-use Task requests, use the [Vida API Skill](/docs/api-reference/vida-api-skill).
</Note>