Task lifecycle

After you call sendToHuman(), each task moves through a small set of statuses until a human handles it, it expires, or you cancel it. Use getTask and cancelTask when you manage tasks outside the built-in webhook or polling flows—for example when you store taskId in your database and check status from a cron job or admin tool.

Task statuses

The public id you pass to getTask and cancelTask is task.taskId from the sendToHuman() response—not the internal Convex document id.

getTask

Fetch the current state of a task by its public id.

import { robotrock } from "@/lib/robotrock";

const task = await robotrock.getTask("task_9f8f31e2-8ac2-4f3e-a6e4-c1f58b2d6d74");

if (!task) {
  console.log("Task not found");
} else if (task.status === "handled" && task.handled) {
  console.log("Action:", task.handled.action.id);
  console.log("Data:", task.handled.action.data);
} else {
  console.log("Status:", task.status);
}

Response shape

getTask returns a Task object:

{
  id: string;
  createdAt: Date;
  status: "pending" | "open" | "handled" | "expired";
  context: TaskContext;
  validUntil: number; // Unix ms
  handledAt?: number;
  handled?: {
    action: { id: string; data: unknown };
    handledBy?: string;
    userId?: string;
    token?: string;
  };
}

When to use getTask

• Webhook mode — After sendToHuman() returns mode: "created", poll or query status yourself if you do not rely solely on the callback.
• Custom workers — A background job that checks open tasks and nudges reviewers.
• Dashboards — Show approval state in your own UI.

If you want the SDK to block until a human responds, use Polling instead of calling getTask in a loop.

cancelTask

Cancel an open task so it no longer appears in the inbox.

import { robotrock } from "@/lib/robotrock";

await robotrock.cancelTask("task_9f8f31e2-8ac2-4f3e-a6e4-c1f58b2d6d74");

Use cancelTask when the underlying work was aborted—for example a deploy was rolled back before anyone approved it.

Related

• Send to human — send tasks and receive taskId
• Webhooks — get handled results via HTTP callback
• Polling — wait in-process with sendToHuman() when no webhook is configured