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

<CodeGroup>
  ```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);
  ```
</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`, `multiple_files`, `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 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](/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: 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

<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>
  Call this before [Approve Task](/api-reference/endpoint/v2/tasks/approve) 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`.
</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** - 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