Get Task

Endpoint

GET /v2/tasks/{task_id}

Authentication

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

Authorization: Bearer your_access_token

Required scope: tasks:read

Path Parameters

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

Request Example

curl -X GET "https://platform.chamelio.ai/v2/tasks/12345" \
  -H "Authorization: Bearer your_access_token"

import requests

task_id = 12345

url = f"https://platform.chamelio.ai/v2/tasks/{task_id}"
headers = {
    "Authorization": "Bearer your_access_token"
}

response = requests.get(url, headers=headers)
print(response.json())

const taskId = 12345;

const response = await fetch(
  `https://platform.chamelio.ai/v2/tasks/${taskId}`,
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer your_access_token'
    }
  }
);

const data = await response.json();
console.log(data);

Response

Success Response

Status Code: 200 OK

{
  "task": {
    "task_id": 12345,
    "task_url": "https://app.chamelio.ai/workflows/tasks/12345",
    "task_title": "Vendor Contract Review - Acme Corporation",
    "workflow_id": "vendor_contract_review",
    "workflow_name": "Vendor Contract Review",
    "workflow_version": 1,
    "workflow_state_id": "ws_abc123",
    "status": "in_progress",
    "priority": "high",
    "current_step_run_id": "sr_002",
    "current_step_id": "review_step",
    "current_step_name": "AI Review",
    "current_step_type": "review",
    "created_at": "2025-01-20T10:30:00Z",
    "updated_at": "2025-01-20T10:35:00Z",
    "completed_at": null,
    "owner_email": "john.doe@example.com",
    "assignee_email": "legal@example.com",
    "collaborator_emails": ["contracts@example.com"],
    "requester_email": "john.doe@example.com",
    "step_runs": [
      {
        "step_run_id": "sr_001",
        "step_id": "intake_step",
        "step_name": "Document Intake",
        "step_type": "intake",
        "status": "completed",
        "variables": [
          {
            "variable_type": "text",
            "value": "Acme Corporation",
            "step_id": "intake_step",
            "variable_id": "vendor_name",
            "variable_title": "Vendor Name"
          }
        ]
      }
    ],
    "variables": [
      {
        "variable_type": "text",
        "value": "Acme Corporation",
        "step_id": "intake_step",
        "variable_id": "vendor_name",
        "variable_title": "Vendor Name"
      },
      {
        "variable_type": "number",
        "value": 150000,
        "step_id": "intake_step",
        "variable_id": "contract_value",
        "variable_title": "Contract Value"
      },
      {
        "variable_type": "email",
        "value": "legal@example.com",
        "step_id": "intake_step",
        "variable_id": "reviewer_email",
        "variable_title": "Reviewer Email"
      }
    ]
  }
}

Response Fields

Field	Type	Description
`task`	object	Complete task state including status and variables

Task Object Fields

Field	Type	Description
`task_id`	integer	Unique identifier for the task
`task_url`	string or null	Direct URL to the task in the Chamelio web application
`task_title`	string or null	Human-readable title of the task
`workflow_id`	string	Identifier of the workflow this task is running
`workflow_name`	string or null	Human-readable workflow name
`workflow_version`	integer	Workflow version number
`workflow_state_id`	string	Identifier for the specific workflow state
`status`	string	Current task status: `created`, `in_progress`, `pending`, `completed`, `cancelled`, `failed`, `archived`, `rejected`, `on_hold`
`priority`	string or null	Task priority: `low`, `medium`, `high`
`current_step_run_id`	string or null	ID of the currently executing step run
`current_step_id`	string or null	ID of the step currently being executed (null if completed)
`current_step_name`	string or null	Name of the current step (null if completed)
`current_step_type`	string or null	Type of the current step (e.g., `"approval"`, `"review"`, `"intake"`, `"signature"`)
`created_at`	string	ISO 8601 timestamp when the task was created
`updated_at`	string	ISO 8601 timestamp of the last task update
`completed_at`	string or null	ISO 8601 timestamp when the task completed (null if not yet completed)
`owner_email`	string or null	Email of the user who owns the task
`assignee_email`	string or null	Email of the user currently assigned to the task
`collaborator_emails`	array of strings	Emails of users collaborating on the task
`requester_email`	string or null	Email of the user who requested the task
`step_runs`	array	History of step executions with their collected variables
`variables`	array	All variables aggregated across all step runs

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., `"intake"`, `"approval"`, `"signature"`, `"review"`)
`status`	string	Step run status: `initiated`, `pending`, `in_progress`, `completed`, `failed`, `rejected`, `cancelled`
`variables`	array	Variables collected during this step run

Variable Object Fields

Used in both step_runs[].variables and the top-level variables array.

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

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.

{
  "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.

{
  "detail": "Invalid access token"
}

403 Forbidden

Returned when the token lacks the required scope:

{
  "detail": "Insufficient scope; this endpoint requires: tasks:read"
}

Or when the user may not access this task:

{
  "detail": "You do not have access to this resource"
}

404 Not Found

Returned when the task does not exist.

{
  "detail": "Not found"
}

429 Too Many Requests

Returned when your organization exceeds its per-minute request limit.

{
  "detail": "Rate limit exceeded"
}

500 Internal Server Error

Returned when the request fails due to a server error.

{
  "detail": "Failed to get task"
}

Notes

The task is read as the access token’s user. You get 403 unless that user is a participant on the task, an acl_read collaborator on it, or a collaborator or manager on its workflow.

Poll this endpoint periodically to monitor task progress.

Use current_step_id and current_step_type to understand which step the workflow is currently executing. If current_step_type is "approval", use the Get Approval Details endpoint for more information about the approval step.

Use Cases

This endpoint is useful for:

Status monitoring - Track workflow progress and completion
Variable retrieval - Get values collected during workflow execution
Step history - Review which steps have run and what data each collected
Debugging - Understand where a workflow is stuck or failed
User notifications - Display current workflow status in your application

Overview

API Key Access

OAuth App Access

Webhooks

Endpoint

Authentication

Path Parameters

Request Example

Response

Success Response

Response Fields

Task Object Fields

Step Run Object Fields

Variable Object Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases

​Endpoint

​Authentication

​Path Parameters

​Request Example

​Response

​Success Response

​Response Fields

​Task Object Fields

​Step Run Object Fields

​Variable Object Fields

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​429 Too Many Requests

​500 Internal Server Error

​Notes

​Use Cases

Endpoint

Authentication

Path Parameters

Request Example

Response

Success Response

Response Fields

Task Object Fields

Step Run Object Fields

Variable Object Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases