> ## 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 /tasks/{task_id}/approval-details
```

## Authentication

This endpoint requires authentication via API key. Include your API key in the `X-API-Key` header:

```bash theme={null}
X-API-Key: ca_your_api_key_here
```

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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://platform.chamelio.ai/tasks/12345/approval-details?include_files=true" \
    -H "X-API-Key: ca_your_api_key_here"
  ```

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

  task_id = 12345

  url = f"https://platform.chamelio.ai/tasks/{task_id}/approval-details"
  headers = {
      "X-API-Key": "ca_your_api_key_here"
  }
  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/tasks/${taskId}/approval-details?include_files=true`,
    {
      method: 'GET',
      headers: {
        'X-API-Key': 'ca_your_api_key_here'
      }
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## 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`, `select`, `multi_select`, `user_entity`, `business`, `dynamic_list`, `dynamic_table`, `number_with_currency`, `conversation` |
| `value`         | any    | Current value of the variable (string, number, boolean, array, or null)                                                                                                                                  |
| `step_id`       | string | ID of the step that collected this variable                                                                                                                                                              |
| `variable_id`   | string | Unique identifier for the variable                                                                                                                                                                       |

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

### 401 Unauthorized

Returned when authentication fails. See the [authentication errors](/api-reference/introduction#authentication-errors) section for details.

```json theme={null}
{
  "detail": "Invalid API key"
}
```

### 404 Not Found

Returned when the task doesn't exist or you don't have access to it.

```json theme={null}
{
  "detail": "Task not found"
}
```

### 409 Conflict

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

```json theme={null}
{
  "detail": "Task is not at a pending approval step"
}
```

### 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"
    }
  ]
}
```

### 500 Internal Server Error

Returned when the request fails due to a server error.

```json theme={null}
{
  "detail": "Failed to get approval details"
}
```

## Notes

<Info>
  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.
</Info>

<Tip>
  Use this endpoint before calling [Approve Task](/api-reference/endpoint/tasks/approve) to verify the task is ready for approval and inspect what variables need review. Set `include_files=true` when you need to download file attachments for review.
</Tip>

<Warning>
  Presigned download URLs in the `files` array expire. Check the `expires_at` field and request new URLs if they have expired.
</Warning>

## Use Cases

This endpoint is useful for:

* **Custom approval UIs** - Build approval interfaces that display full context including variables and files
* **Pre-approval validation** - Check eligible approvers and pending variables before submitting a decision
* **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