> ## 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 Message History

> Get full conversation history for rendering a chat UI

# Get Task Message History

Retrieve the complete message history for a task. This endpoint is designed for developers who want to render their own chat UI and manage conversation history independently.

## Request

```bash theme={null}
GET /api/v1/tasks/{id}/history
Authorization: Bearer {api_key}
```

### Path Parameters

| Parameter | Type   | Description                |
| --------- | ------ | -------------------------- |
| `id`      | string | The unique task identifier |

## Response

```json theme={null}
{
  "success": true,
  "data": {
    "taskId": "c37c1d78-4d23-4e53-949a-ddd775f25e01",
    "conversationId": "1769442659997-70avfyadp",
    "status": "completed",
    "messages": [
      {
        "id": "msg-1",
        "role": "user",
        "content": "Analyze this CSV file",
        "createdAt": "2026-01-26T15:50:54.870Z",
        "attachedFiles": [
          { "name": "data.csv", "path": "uploads/data.csv" }
        ]
      },
      {
        "id": "msg-2",
        "role": "assistant",
        "content": "I analyzed the CSV file. Here are my findings...",
        "createdAt": "2026-01-26T15:50:59.998Z",
        "thoughts": [
          { "subject": "Analyzing", "description": "Reading the CSV structure..." }
        ],
        "toolCalls": [
          {
            "callId": "tc-1",
            "toolName": "read_file",
            "status": "success",
            "args": { "path": "uploads/data.csv" },
            "output": "column1,column2\nvalue1,value2"
          }
        ]
      }
    ]
  }
}
```

### Response Fields

| Field            | Type   | Description                         |
| ---------------- | ------ | ----------------------------------- |
| `taskId`         | string | The task identifier                 |
| `conversationId` | string | The conversation identifier         |
| `status`         | string | Current task status                 |
| `messages`       | array  | All messages in chronological order |

### Message Object

| Field           | Type               | Description                                          |
| --------------- | ------------------ | ---------------------------------------------------- |
| `id`            | string             | Unique message identifier                            |
| `role`          | string             | `user` or `assistant`                                |
| `content`       | string             | Message text content                                 |
| `createdAt`     | string             | ISO timestamp when message was created               |
| `attachedFiles` | array \| undefined | Files attached to this message (user messages only)  |
| `thoughts`      | array \| undefined | Agent's thinking/reasoning (assistant messages only) |
| `toolCalls`     | array \| undefined | Tool executions (assistant messages only)            |

<Note>
  For user messages with file uploads, the `content` field contains only the user's message text - the file upload prefix is stripped and the files are listed in `attachedFiles` instead.
</Note>

### Attached File Object

| Field  | Type   | Description                                  |
| ------ | ------ | -------------------------------------------- |
| `name` | string | Original filename (e.g., "data.csv")         |
| `path` | string | Path in workspace (e.g., "uploads/data.csv") |

### Thought Object

| Field         | Type   | Description                  |
| ------------- | ------ | ---------------------------- |
| `subject`     | string | Brief subject of the thought |
| `description` | string | Detailed reasoning           |

### Tool Call Object

| Field         | Type   | Description                                             |
| ------------- | ------ | ------------------------------------------------------- |
| `callId`      | string | Unique tool call identifier                             |
| `toolName`    | string | Name of the tool executed                               |
| `status`      | string | `pending`, `executing`, `success`, `error`, `cancelled` |
| `args`        | object | Arguments passed to the tool                            |
| `output`      | string | Tool output (when completed)                            |
| `description` | string | Human-readable description of the action                |

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -s https://api.sigmic.ai/api/v1/tasks/c37c1d78-4d23-4e53-949a-ddd775f25e01/history \
    -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}/history`,
    {
      headers: {
        'Authorization': 'Bearer sigmic_your_key_here'
      }
    }
  );

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

  // Render messages in your chat UI
  data.messages.forEach(msg => {
    if (msg.role === 'user') {
      renderUserMessage(msg.content, msg.attachedFiles);
    } else {
      renderAssistantMessage(msg.content, msg.thoughts, msg.toolCalls);
    }
  });
  ```

  ```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}/history',
      headers={'Authorization': 'Bearer sigmic_your_key_here'}
  )

  data = response.json()['data']

  # Process messages
  for msg in data['messages']:
      print(f"[{msg['role']}]: {msg['content']}")

      if msg.get('attachedFiles'):
          print(f"  Files: {[f['name'] for f in msg['attachedFiles']]}")

      if msg.get('toolCalls'):
          for tc in msg['toolCalls']:
              print(f"  Tool: {tc['toolName']} -> {tc['status']}")
  ```
</CodeGroup>

## Use Cases

### Building a Custom Chat UI

Use this endpoint to hydrate your chat interface with the full conversation history:

```javascript theme={null}
async function loadChatHistory(taskId) {
  const response = await fetch(`${API_BASE}/api/v1/tasks/${taskId}/history`, {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

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

  return data.messages.map(msg => ({
    id: msg.id,
    sender: msg.role === 'user' ? 'You' : 'AI Assistant',
    text: msg.content,
    timestamp: new Date(msg.createdAt),
    files: msg.attachedFiles || [],
    thinking: msg.thoughts || [],
    tools: msg.toolCalls || []
  }));
}
```

### Displaying File Attachments

```javascript theme={null}
function renderMessage(message) {
  // Show attached files for user messages
  if (message.attachedFiles?.length > 0) {
    return (
      <div>
        <div className="files">
          {message.attachedFiles.map(file => (
            <span key={file.path}>📎 {file.name}</span>
          ))}
        </div>
        <p>{message.content}</p>
      </div>
    );
  }

  return <p>{message.content}</p>;
}
```

### Displaying Tool Executions

```javascript theme={null}
function renderToolCalls(toolCalls) {
  return toolCalls.map(tc => (
    <div key={tc.callId} className={`tool-call ${tc.status}`}>
      <span className="tool-name">{tc.toolName}</span>
      <span className="status">{tc.status}</span>
      {tc.output && <pre>{tc.output}</pre>}
    </div>
  ));
}
```

## 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 |
| `NO_CONVERSATION` | Task has no conversation history         |