Skip to main content
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

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, except identity fields such as id and target. For example:
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:
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.
For complete retry policy rules and ready-to-use Task requests, use the Vida API Skill.