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

## Populate Contact fields when creating Tasks

For new `call`, `text`, and `email` Tasks, use optional `meta.contact` to populate missing fields on
the recipient's Contact in the Task organization. It accepts the writable fields in the
[Contact field reference](/docs/api-reference/platform-guides/contacts-and-objectives#contact-fields),
except identity fields such as `id` and `target`. For example:

```json theme={null}
{
  "meta": {
    "contact": {
      "name": "Example Person",
      "email": "lead@example.com",
      "address": {
        "state": "LA",
        "zip": "71101"
      },
      "customFields": {
        "vendorLeadCode": "lead-123"
      }
    }
  }
}
```

Strings are trimmed. Null values, blank strings, and empty objects or arrays are ignored. Existing
nonblank fields, `false`, zero, and nonempty arrays are preserved; nested objects fill only missing
leaves. A new Contact uses the supplied name instead of a global-profile default. The Task target,
canonical target phone or email, outbound caller ID, and global user profile do not change.

CSV uploads use the existing dotted metadata columns:

```csv theme={null}
type,accountId,target,taskContext,meta.contact.name,meta.contact.email,meta.contact.address.state,meta.contact.customFields.vendorLeadCode
call,1234,+15551234567,Confirm interest in a demo,Example Person,lead@example.com,LA,lead-123
```

Metadata column paths retain their exact casing. CSV metadata cells are strings, so use JSON Task
creation for boolean, numeric, or array Contact values. Names in `context` or `taskContext` do not
populate Contact fields. This behavior applies at Task creation, not Task updates. Use the Contact
API to replace or clear existing values. Other `meta` keys remain available for filtering and
reporting.

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

For one immediate assignment where the caller wants the final assistant text directly, use
`POST /api/v2/computer/accounts/{targetAccountId}/tasks/execute`. Send `taskContext` and optionally
`title`, `externalTaskId`, `meta`, and `waitSeconds` from 0 through 60. Do not send `type` or
`accountId`. A `200` response means the reply is ready or the Task ended unavailable; inspect
`state`, `resultStatus`, `output`, and `error`. A `202` means work or reply replication is still
pending. Save `taskId` and poll the returned `resultRef.href` with the normal API token. The POST is
not idempotent, so do not retry an uncertain request without first reconciling existing Tasks.

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>