Read task

Endpoint

GET /bot/tasks/{task_id}

Returns a task if the bot user has access to the form of that task.

Returned fields

Main task fields:

• task_id
• form_id
• title
• author_id
• responsible_id
• responsible_ids
• created_at
• last_activity
• is_finished
• status
• due_date_at
• step_id
• step_assignments
• items

How step_assignments are returned

step_assignments contains all assignments associated with the task, including assignments from previous workflow steps.

Each assignment contains:

• assignment_id - assignment ID accepted by POST /bot/tasks/{task_id}/step-return
• step_id - workflow step associated with the assignment
• assignee_id - assigned user ID, or null for a group assignment
• group_assignee_ids - user IDs in a group assignment
• group_name - group name, or null
• step_role_id - assignment role ID
• is_confirmed - assignment confirmation state

To return a task to an earlier step, select an assignment whose step_id belongs to a step before the task's current step_id and send its assignment_id to the return task to step endpoint.

How items are returned

items is an array of top-level task items.

Each item contains:

• item_id
• form_field_id
• form_field_type
• name
• value
• float_value
• date_value
• linked_task_id

How table rows are returned

If an item is a table, it also contains rows.

Each row contains:

• row_id
• position
• items

Each nested row item uses the same shape:

• item_id
• form_field_id
• form_field_type
• name
• value
• float_value
• date_value
• linked_task_id

What is not included automatically

• comments are not included
• files are not included

The current GET /bot/tasks/{task_id} implementation serializes the task, all of its step assignments, and its task_items, including table rows.

Example: read task

GET /bot/tasks/5001
Authorization: Bearer <token>

{
  "success": true,
  "error_message": null,
  "data": {
    "task_id": 5001,
    "form_id": 12,
    "title": "Lead #5001 Lead from website",
    "author_id": 77,
    "responsible_id": 45,
    "responsible_ids": [45],
    "created_at": "2026-03-29T10:00:00+00:00",
    "last_activity": "2026-03-29T10:00:00+00:00",
    "is_finished": false,
    "status": "new",
    "due_date_at": null,
    "step_id": 3,
    "step_assignments": [
      {
        "assignment_id": 120,
        "step_id": 2,
        "assignee_id": 45,
        "group_assignee_ids": [],
        "group_name": null,
        "step_role_id": 1,
        "is_confirmed": true
      },
      {
        "assignment_id": 123,
        "step_id": 3,
        "assignee_id": 45,
        "group_assignee_ids": [],
        "group_name": null,
        "step_role_id": 1,
        "is_confirmed": false
      }
    ],
    "items": [
      {
        "item_id": 7001,
        "form_field_id": 101,
        "form_field_type": "TextField",
        "name": "Title",
        "value": "Lead from website",
        "float_value": null,
        "date_value": null,
        "linked_task_id": null
      },
      {
        "item_id": 7002,
        "form_field_id": 104,
        "form_field_type": "TableField",
        "name": "Products",
        "value": "",
        "float_value": null,
        "date_value": null,
        "linked_task_id": null,
        "rows": [
          {
            "row_id": 8101,
            "position": 1,
            "items": [
              {
                "item_id": 7003,
                "form_field_id": 201,
                "form_field_type": "TextField",
                "name": "Product name",
                "value": "Product A",
                "float_value": null,
                "date_value": null,
                "linked_task_id": null
              }
            ]
          }
        ]
      }
    ]
  }
}

Common errors

• 404 Task not found
• 403 Form access not found
• 429 Rate limit exceeded. Retry after {seconds} seconds