Get Task

Retrieve the details and current status of a specific task, including accumulated output and any pending tool approvals.

Request

GET /api/v1/tasks/{id}
Authorization: Bearer {api_key}

Path Parameters

Parameter	Type	Description
`id`	string	The unique task identifier

Response

Running Task with Pending Approvals

When a task requires tool approval, the response includes a pendingApprovals array:

{
  "success": true,
  "data": {
    "id": "c37c1d78-4d23-4e53-949a-ddd775f25e01",
    "apiKeyId": "82344182-b81e-4f9a-8e7f-c14d8324caac",
    "username": "testuser",
    "sessionId": "80513b3f-9030-4776-a209-f2d96b1abce1",
    "conversationId": "1769442659997-70avfyadp",
    "status": "awaiting_approval",
    "message": "List all files in the project",
    "systemPrompt": null,
    "showInHistory": true,
    "autoExecute": false,
    "env": null,
    "error": null,
    "createdAt": "2026-01-26T15:50:54.870Z",
    "startedAt": "2026-01-26T15:50:59.998Z",
    "completedAt": null,
    "output": {
      "content": "I'll list the files for you...",
      "updatedAt": "2026-01-26T15:51:02.123Z",
      "thoughts": [
        { "subject": "Analyzing", "description": "Looking at the project structure..." }
      ],
      "toolCalls": [
        {
          "callId": "call_123",
          "toolName": "list_files",
          "status": "awaiting_approval",
          "args": { "path": "/uploads" }
        }
      ]
    },
    "pendingApprovals": [
      {
        "callId": "call_123",
        "toolName": "list_files",
        "args": { "path": "/uploads" }
      }
    ]
  }
}

Completed Task

When a task is completed, output contains the final response:

{
  "success": true,
  "data": {
    "id": "c37c1d78-4d23-4e53-949a-ddd775f25e01",
    "apiKeyId": "82344182-b81e-4f9a-8e7f-c14d8324caac",
    "username": "testuser",
    "sessionId": "80513b3f-9030-4776-a209-f2d96b1abce1",
    "conversationId": "1769442659997-70avfyadp",
    "status": "completed",
    "message": "What is 2+2?",
    "systemPrompt": null,
    "showInHistory": true,
    "autoExecute": true,
    "env": null,
    "error": null,
    "createdAt": "2026-01-26T15:50:54.870Z",
    "startedAt": "2026-01-26T15:50:59.998Z",
    "completedAt": "2026-01-26T15:56:03.070Z",
    "output": {
      "content": "The answer to 2+2 is 4.",
      "updatedAt": "2026-01-26T15:56:03.070Z",
      "thoughts": [
        { "subject": "Calculating", "description": "Performing basic arithmetic" }
      ],
      "toolCalls": []
    }
  }
}

Response Fields

Field	Type	Description
`id`	string	Unique task identifier
`apiKeyId`	string	ID of the API key used to create the task
`username`	string	Username associated with the API key
`sessionId`	string	ID of the agent session
`conversationId`	string	ID of the conversation for history
`status`	string	Current task status
`message`	string	Original task message
`systemPrompt`	string \| null	Custom system prompt if provided
`showInHistory`	boolean	Whether task appears in conversation history
`autoExecute`	boolean	Whether tools auto-execute
`env`	object \| null	Non-sensitive env vars provided at creation
`error`	string \| null	Error message if task failed
`createdAt`	string	ISO timestamp when task was created
`startedAt`	string \| null	ISO timestamp when execution started
`completedAt`	string \| null	ISO timestamp when task completed
`output`	object \| undefined	Accumulated output (present for running and completed tasks)
`pendingApprovals`	array \| undefined	Tool calls awaiting approval (present when non-empty)

Output Object

The output field provides a unified view of the task’s response, whether the task is still running or has completed. Use the status field to determine if the content is partial (running) or final (completed/failed/cancelled).

Field	Type	Description
`content`	string	Accumulated text response (partial while running, final when completed)
`updatedAt`	string	ISO timestamp when the output was last updated
`thoughts`	array \| undefined	Agent’s thinking process entries
`toolCalls`	array \| undefined	Tool executions with their current status

Tool Call Structure

Each entry in toolCalls has the following structure:

Field	Type	Description
`callId`	string	Unique identifier for the tool call
`toolName`	string	Name of the tool being executed
`status`	string	Tool execution status
`args`	object	Arguments passed to the tool
`output`	string	Tool output (when completed)
`description`	string	Human-readable description of the tool call

Tool Call Status Values:

Status	Description
`pending`	Tool call queued, not yet started
`awaiting_approval`	Waiting for user approval
`executing`	Currently running
`success`	Completed successfully
`error`	Failed with an error
`cancelled`	User cancelled the call

Task Status Values

Status	Description
`pending`	Task created, not yet started
`running`	Task is currently executing
`awaiting_approval`	Waiting for tool call approval
`completed`	Task finished successfully
`failed`	Task failed with an error
`cancelled`	Task was cancelled

Use output.updatedAt to track when content was last accumulated. This is useful for detecting changes when polling.

Examples

curl -s https://api.sigmic.ai/api/v1/tasks/c37c1d78-4d23-4e53-949a-ddd775f25e01 \
  -H "Authorization: Bearer sigmic_your_key_here"

Use Cases

Polling for Progress

Use the output field to show real-time progress without maintaining an SSE connection:

async function pollTaskProgress(taskId, onProgress, maxAttempts = 120) {
  let lastUpdatedAt = null;

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.sigmic.ai/api/v1/tasks/${taskId}`,
      { headers: { 'Authorization': 'Bearer sigmic_your_key_here' } }
    );

    const { data: task } = await response.json();

    // Check if output has been updated since last poll
    if (task.output && task.output.updatedAt !== lastUpdatedAt) {
      lastUpdatedAt = task.output.updatedAt;
      onProgress({
        content: task.output.content,
        thoughts: task.output.thoughts || [],
        toolCalls: task.output.toolCalls || [],
        updatedAt: task.output.updatedAt,
        isComplete: ['completed', 'failed', 'cancelled'].includes(task.status)
      });
    }

    // Check if task ended
    if (['completed', 'failed', 'cancelled'].includes(task.status)) {
      if (task.status === 'completed') {
        return task;
      }
      throw new Error(`Task ${task.status}: ${task.error}`);
    }

    // Poll every 500ms for responsive updates
    await new Promise(resolve => setTimeout(resolve, 500));
  }

  throw new Error('Task did not complete in time');
}

// Usage
pollTaskProgress('task-123', (progress) => {
  console.log('Content:', progress.content);
  console.log('Last updated:', progress.updatedAt);
  if (progress.isComplete) {
    console.log('Final result received!');
  }
});

Polling for Completion (Simple)

If you only need to check final task status:

async function waitForCompletion(taskId, maxAttempts = 60) {
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.sigmic.ai/api/v1/tasks/${taskId}`,
      { headers: { 'Authorization': 'Bearer sigmic_your_key_here' } }
    );

    const { data: task } = await response.json();

    if (task.status === 'completed') {
      console.log('Final response:', task.output?.content);
      return task;
    }

    if (task.status === 'failed' || task.status === 'cancelled') {
      throw new Error(`Task ${task.status}: ${task.error}`);
    }

    // Wait 1 second before polling again
    await new Promise(resolve => setTimeout(resolve, 1000));
  }

  throw new Error('Task did not complete in time');
}

Checking for Pending Approvals

The pendingApprovals array provides a convenient way to discover tool calls awaiting approval without an active SSE connection:

const { data: task } = await response.json();

if (task.pendingApprovals?.length > 0) {
  for (const approval of task.pendingApprovals) {
    console.log(`Tool "${approval.toolName}" requires approval`);
    console.log('Args:', approval.args);
    console.log('Call ID:', approval.callId);

    // Approve the tool call
    await fetch(
      `${BASE_URL}/api/v1/tasks/${task.id}/tools/${approval.callId}/approve`,
      {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer sigmic_your_key_here',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ outcome: 'proceed_once' })
      }
    );
  }
}

Pending Approval Object

Field	Type	Description
`callId`	string	Tool call ID (use with the approve endpoint)
`toolName`	string	Name of the tool awaiting approval
`args`	object	Arguments that will be passed to the tool

Errors

Code	Description
`AUTH_REQUIRED`	No authentication provided
`INVALID_API_KEY`	Invalid or expired API key
`NOT_FOUND`	Task with the specified ID was not found

Getting Started

Chat UI

Embeddable Widget

Task API

Concepts

Examples

Get Task

Get Task

Request

Path Parameters

Response

Running Task with Pending Approvals

Completed Task

Response Fields

Output Object

Tool Call Structure

Task Status Values

Examples

Use Cases

Polling for Progress

Polling for Completion (Simple)

Checking for Pending Approvals

Pending Approval Object

Errors

Getting Started

Chat UI

Embeddable Widget

Task API

Concepts

Examples

Documentation Index

​Get Task

​Request

​Path Parameters

​Response

​Running Task with Pending Approvals

​Completed Task

​Response Fields

​Output Object

​Tool Call Structure

​Task Status Values

​Examples

​Use Cases

​Polling for Progress

​Polling for Completion (Simple)

​Checking for Pending Approvals

​Pending Approval Object

​Errors

Get Task

Request

Path Parameters

Response

Running Task with Pending Approvals

Completed Task

Response Fields

Output Object

Tool Call Structure

Task Status Values

Examples

Use Cases

Polling for Progress

Polling for Completion (Simple)

Checking for Pending Approvals

Pending Approval Object

Errors