> ## 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.

# Get Approval Details

> Retrieve approval step details, eligible approvers, and pending variables for a task

## Endpoint

```
GET /v2/tasks/{task_id}/approval-details
```

## Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:

```bash theme={null}
Authorization: Bearer your_access_token
```

**Required scope:** `tasks:read`

## Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `task_id` | integer | Yes | Unique identifier for the task |

## Query Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `include_files` | boolean | No | Include presigned download URLs for file-type variables. Defaults to `false` |

## Request Example

```bash cURL theme={null}
curl -X GET "https://platform.chamelio.ai/v2/tasks/12345/approval-details?include_files=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}/approval-details"
headers = {
    "Authorization": "Bearer your_access_token"
}
params = {
    "include_files": 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}/approval-details?include_files=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,
  "step_run": {
    "step_run_id": "sr_abc123",
    "step_id": "approval_step",
    "step_name": "Legal Approval",
    "step_type": "approval",
    "status": "pending",
    "variables": [
      {
        "variable_type": "text",
        "value": "Acme Corporation",
        "step_id": "intake_step",
        "variable_id": "vendor_name"
      }
    ]
  },
  "eligible_approvers_active": ["manager@example.com"],
  "next_eligible_approvers": ["director@example.com"],
  "variables_to_approve": [
    {
      "variable_type": "number",
      "value": 150000,
      "step_id": "intake_step",
      "variable_id": "contract_value"
    },
    {
      "variable_type": "file",
      "value": "att_789",
      "step_id": "intake_step",
      "variable_id": "contract_file"
    }
  ],
  "files": [
    {
      "file_id": "att_789",
      "file_name": "contract_draft.pdf",
      "content_type": "application/pdf",
      "download_url": "https://storage.example.com/presigned-url...",
      "expires_at": "2025-01-20T12:00:00Z",
      "variable_id": "contract_file"
    }
  ]
}
```

### Response Fields

| Field | Type | Description |
| - | - | - |
| `task_id` | integer | ID of the task |
| `step_run` | object | Current approval step run details |
| `eligible_approvers_active` | array of strings | Emails of users currently eligible to approve |
| `next_eligible_approvers` | array of strings | Emails of users next in line for sequential approval (empty for parallel) |
| `variables_to_approve` | array | Variables pending approval review |
| `files` | array | Presigned download info for file-type variables (only present when `include_files=true`) |

### Step Run Object Fields

| Field | Type | Description |
| - | - | - |
| `step_run_id` | string | Unique identifier for this step run |
| `step_id` | string | Identifier for the step definition |
| `step_name` | string | Human-readable step name |
| `step_type` | string | Type of workflow component (e.g., `"approval"`) |
| `status` | string | Step run status: `initiated`, `pending`, `in_progress`, `completed`, `failed`, `rejected`, `cancelled` |
| `variables` | array | Variables associated with this step run |

### Variable Object Fields

Used in both `step_run.variables` and `variables_to_approve`.

| Field | Type | Description |
| - | - | - |
| `variable_type` | string | Type of the variable: `text`, `number`, `boolean`, `date`, `email`, `file`, `multiple_files`, `select`, `multi_select`, `user_entity`, `business`, `dynamic_list`, `dynamic_table`, `number_with_currency`, `conversation`, `reference_file`, `reference_vault_item`, `formula` |
| `value` | any | Current value of the variable (string, number, boolean, array of strings, or null) |
| `step_id` | string | ID of the step that collected this variable |
| `variable_id` | string | Unique identifier for the variable |
| `variable_title` | string or null | Human-readable variable name |

### File Object Fields

Only populated when `include_files=true`. Contains presigned download info for file-type variables.

| Field | Type | Description |
| - | - | - |
| `file_id` | string | Unique file identifier |
| `file_name` | string | Name of the file |
| `content_type` | string | MIME type of the file |
| `download_url` | string | Presigned URL for downloading the file |
| `expires_at` | string | ISO 8601 timestamp when the download URL expires |
| `variable_id` | string | ID of the variable this file belongs to |

## 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](https://docs.chamelio.ai/api-reference/oauth-apps.md#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: tasks: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"
}
```

### 409 Conflict

Returned when the task is not currently at a pending approval step.

```json theme={null}
{
  "detail": "The task is not in a state that allows this operation"
}
```

### 422 Validation Error

Returned when request parameters are invalid.

```json theme={null}
{
  "detail": [
    {
      "loc": ["path", "task_id"],
      "msg": "value is not a valid integer",
      "type": "type_error.integer"
    }
  ]
}
```

### 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 get approval details"
}
```

## Notes

> [!NOTE]
>
> For **sequential** approval workflows, `eligible_approvers_active` shows the approver(s) whose turn it
> is now, while `next_eligible_approvers` shows who comes after. For **parallel** approval workflows, all
> eligible approvers appear in `eligible_approvers_active` and `next_eligible_approvers` is empty.

> [!TIP]
>
> Call this before [Approve Task](https://docs.chamelio.ai/api-reference/endpoint/v2/tasks/approve.md) and check whether the access
> token's user appears in `eligible_approvers_active`. Approving as a user who is not an eligible
> approver returns `400`.

> [!WARNING]
>
> Presigned download URLs in the `files` array expire. Check the `expires_at` field and request new URLs
> if they have expired.

## Use Cases

This endpoint is useful for:

* **Custom approval UIs** - Build approval interfaces that display full context including variables and files
* **Pre-approval validation** - Confirm the current user is an eligible approver before submitting
* **File review workflows** - Download file attachments for external review before approving
* **Approval routing** - Determine sequential vs parallel approval order and who is next in line
