> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chamelio.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# List Task Files
> Retrieve all files associated with a workflow task
## Endpoint
```
GET /v2/tasks/{task_id}/files
```
## Authentication
This endpoint requires an OAuth access token. Send it as a bearer token:
```bash theme={null}
Authorization: Bearer your_access_token
```
**Required scope:** `files:read`
This endpoint hangs off `/tasks` but is gated on `files:read`, not `tasks:read`, because it returns file
references. A token with only `tasks:read` gets a `403`.
## Path Parameters
| Parameter | Type | Required | Description |
| --------- | ------- | -------- | ------------------------------ |
| `task_id` | integer | Yes | Unique identifier for the task |
## Query Parameters
| Parameter | Type | Required | Description |
| --------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `include_attachments` | boolean | No | When `true`, also return task-level and activity-log attachments in the `attachments` field. Defaults to `false`. |
## Request Example
```bash cURL theme={null}
curl -X GET "https://platform.chamelio.ai/v2/tasks/12345/files?include_attachments=true" \
-H "Authorization: Bearer your_access_token"
```
```python Python theme={null}
import requests
task_id = 12345
url = f"https://platform.chamelio.ai/v2/tasks/{task_id}/files"
headers = {
"Authorization": "Bearer your_access_token"
}
params = {
"include_attachments": True
}
response = requests.get(url, headers=headers, params=params)
print(response.json())
```
```javascript JavaScript theme={null}
const taskId = 12345;
const response = await fetch(
`https://platform.chamelio.ai/v2/tasks/${taskId}/files?include_attachments=true`,
{
method: 'GET',
headers: {
'Authorization': 'Bearer your_access_token'
}
}
);
const data = await response.json();
console.log(data);
```
## Response
### Success Response
**Status Code:** `200 OK`
```json theme={null}
{
"task_id": 12345,
"files": [
{
"file_id": "document_789",
"file_name": "acme_contract.pdf",
"variable_id": "contract_file",
"created_at": "2025-01-20T10:30:00Z",
"step_id": "intake_step"
},
{
"file_id": "document_790",
"file_name": "reviewed_contract.pdf",
"variable_id": null,
"created_at": "2025-01-20T10:45:00Z",
"step_id": "review_step"
},
{
"file_id": "attachment_123",
"file_name": "insurance_certificate.pdf",
"variable_id": "insurance_doc",
"created_at": "2025-01-20T11:00:00Z",
"step_id": "approval_step"
}
],
"total_files": 3,
"attachments": [
{
"file_id": "attachment_456",
"file_name": "email_thread.pdf",
"variable_id": null,
"created_at": "2025-01-20T12:00:00Z",
"step_id": null
}
]
}
```
### Response Fields
| Field | Type | Description |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `task_id` | integer | ID of the task |
| `files` | array | List of files associated with the task (maximum 10 files returned) |
| `total_files` | integer | Total number of files for this task |
| `attachments` | array | Task-level and activity-log attachments. Only populated when `include_attachments=true`; otherwise an empty array. Each entry uses the same File Object fields below (with `variable_id` and `step_id` always `null`). |
### File Object Fields
| Field | Type | Description |
| ------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `file_id` | string | Unique file identifier (format: `document_{id}` for documents, `attachment_{id}` for attachments) |
| `file_name` | string | Name of the file |
| `variable_id` | string or null | ID of the variable this file is associated with. `null` if the file was generated by a step rather than collected into a variable |
| `created_at` | string | ISO 8601 timestamp when the file was created/uploaded |
| `step_id` | string or null | ID of the workflow step that created or collected this file. `null` for task-level attachments |
## Error Responses
### 400 Bad Request
Returned when the access token has no user behind it.
`client_credentials` tokens act as the admin who created the application, so this applies only to
tokens issued before application creators were recorded.
```json theme={null}
{
"detail": "client_credentials tokens are not associated with a user"
}
```
### 401 Unauthorized
Returned when the access token is missing, unknown, revoked, or expired, or when an `X-API-Key` was
sent instead of a bearer token. See [OAuth error responses](/api-reference/oauth-apps#error-responses).
```json theme={null}
{
"detail": "Invalid access token"
}
```
### 403 Forbidden
Returned when the token lacks the required scope:
```json theme={null}
{
"detail": "Insufficient scope; this endpoint requires: files:read"
}
```
Or when the user may not access this task:
```json theme={null}
{
"detail": "You do not have access to this resource"
}
```
### 404 Not Found
Returned when the task does not exist.
```json theme={null}
{
"detail": "Not found"
}
```
### 429 Too Many Requests
Returned when your organization exceeds its per-minute request limit.
```json theme={null}
{
"detail": "Rate limit exceeded"
}
```
### 500 Internal Server Error
Returned when the request fails due to a server error.
```json theme={null}
{
"detail": "Failed to list task files"
}
```
## Notes
This endpoint returns at most 10 files. If the task has more than 10 files, only the first 10
are returned. Use the `total_files` count to determine if there are more files.
Use the `file_id` from this response with the
[Download File](/api-reference/endpoint/v2/files/download) endpoint to retrieve the actual file content.
File IDs are prefixed with `document_` for documents and `attachment_` for attachments. Ensure you pass
the complete file ID including the prefix when downloading files.
Set `include_attachments=true` to also retrieve task-level and activity-log attachments (such as emailed
documents) in the `attachments` array. These are not tied to a workflow variable or step, so their
`variable_id` and `step_id` are `null`.
## Use Cases
This endpoint is useful for:
* **File inventory** - List all files involved in a workflow task
* **Document tracking** - Track which documents were uploaded or generated at each step
* **Bulk download** - Retrieve file IDs for downloading all task-related files
* **Audit trails** - Document what files were part of a workflow execution