Skip to main content

Update task

Update a task by ID. Session requests use the signed-in user; developer-key requests resolve actorUserId or the key owner.

PUT/api/task-queue/{task_id}
HTTP referenceScope tasks:writeUpdated September 27, 2026

This page documents the canonical HTTP contract for this endpoint.

Changing status to completed, skipped, or failed runs task-completion behavior, which can advance a linked sequence and return follow-up fields such as next_task or action_required. Status updates are state-changing operations.

Path parameters

  • task_idrequired

    string

    Task ID.

Query parameters

  • actorUserId · optional

    string

    Optional actor override.

Body parameters

  • task_status · optional

    string

    pending, scheduled, paused, completed, failed, or skipped.

  • priority · optional

    string

    low, medium, or high.

  • due_date · optional

    string (ISO datetime)

    Task due date.

  • content · optional

    object

    Updated channel content payload.

  • notes · optional

    string

    Optional task notes.

  • instructions · optional

    string

    Optional task instructions.

  • started_at · optional

    string (ISO datetime)

    Start timestamp.

  • completed_at · optional

    string (ISO datetime)

    Completion timestamp.

  • attempt_count · optional

    integer

    Attempt counter.

  • last_outcome · optional

    string

    Last task outcome.

  • task_group_id · optional

    string

    Task group ID; null clears it.

  • origin · optional

    string

    sequence, manual, or system.

  • sender_bindings · optional

    object

    Channel-keyed sender binding values.

  • sender_account_id · optional

    string

    Sender account override, subject to actor access and sender identity lock.

  • sender_user_id · optional

    string

    Sender owner override.

  • senderBindings · optional

    object

    Camel-case alias for sender_bindings.

  • senderAccountId · optional

    string

    Camel-case alias for sender_account_id.

  • senderUserId · optional

    string

    Camel-case alias for sender_user_id.

  • email_type · optional

    string

    personal or bulk.

  • email_provider · optional

    string

    gmail, microsoft, instantly, smartlead, or internal.

  • provider_account_email · optional

    string

    Sender mailbox address.

  • campaign_id · optional

    string

    Provider campaign ID.

  • campaign_step · optional

    integer

    Provider campaign step.

  • related_activity_id · optional

    string

    Related activity ID.

  • sequence_execution_mode · optional

    string

    Sequence execution mode.

  • sequence_blocks · optional

    boolean

    Sequence blocking flag.

  • subject · optional

    string

    Email subject field used by approval flows.

  • body · optional

    string

    Email body field used by approval flows.

  • body_format · optional

    string

    Email body format.

  • draft_feedback · optional

    object

    Optional feedback captured when completing an AI-drafted task.

Errors

StatusMeaning
400Invalid payload or actor.
401Invalid API key or missing auth.
403Missing tasks:write scope.
404Task not found.

Docs