> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sigmic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Task

> Get details of a specific task

# Get Task

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

## Request

```bash theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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             |

<Note>
  Use `output.updatedAt` to track when content was last accumulated. This is useful for detecting changes when polling.
</Note>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -s https://api.sigmic.ai/api/v1/tasks/c37c1d78-4d23-4e53-949a-ddd775f25e01 \
    -H "Authorization: Bearer sigmic_your_key_here"
  ```

  ```javascript JavaScript theme={null}
  const taskId = 'c37c1d78-4d23-4e53-949a-ddd775f25e01';

  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();
  console.log(`Task status: ${task.status}`);
  ```

  ```python Python theme={null}
  import requests

  task_id = 'c37c1d78-4d23-4e53-949a-ddd775f25e01'

  response = requests.get(
      f'https://api.sigmic.ai/api/v1/tasks/{task_id}',
      headers={'Authorization': 'Bearer sigmic_your_key_here'}
  )

  task = response.json()['data']
  print(f'Task status: {task["status"]}')
  ```
</CodeGroup>

## Use Cases

### Polling for Progress

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

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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](/tasks/approve)) |
| `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 |