List tasks

​

Lists tasks, a page at a time. Only active tasks come back unless you ask for others with filter[scope].

Descriptions are left out of list responses — retrieve a task on its own to read description_html or description_plain_text.

billable is left out entirely for a token that is not allowed to see billing. Treat it as an optional key rather than assuming it is always there.

Filtering

  • filter[assignee_id] — one or more user ids, or me for whoever the token belongs to. Note this takes a user id, not a team member id.
  • filter[scope] — which tasks to include: active (the default), completed, archived, all, my_tasks, planned (has a due date), unplanned (has none) or upcoming_and_overdue.
  • filter[due] — a named date window: today, overdue, today_or_overdue, this_week, this_month or upcoming. Cannot be combined with filter[due_from] or filter[due_to].
  • filter[due_from] and filter[due_to] — an explicit date range. Either bound works on its own.
  • filter[priority] — one or more of urgent, high, medium, low.
  • filter[project_id] — one or more project ids.
  • filter[tag_id] — one or more tag ids.
  • filter[task_status_id] — one or more task status ids. This one also widens the default scope: tasks in the given columns come back whether they are active, completed or archived.
  • filter[title] — searches task titles, ignoring case.
Query Parameters
  • page[number]
    Type: integer
    min:  
    1

    Page to return, starting at 1.

  • page[size]
    Type: integer
    min:  
    1
    max:  
    100

    Records per page. Defaults to 25; anything above 100 is reduced to 100.

  • filter[assignee_id]
    Type: string

    One or more user ids, comma-separated or repeated. Pass me for whoever the token belongs to.

  • filter[scope]
    Type: string enum

    Which tasks to include. Defaults to active.

    values
    • active
    • completed
    • archived
    • all
    • upcoming_and_overdue
    • unplanned
    • planned
    • my_tasks
  • filter[due]
    Type: string enum

    A named due-date window. Cannot be combined with filter[due_from] or filter[due_to].

    values
    • today
    • overdue
    • today_or_overdue
    • this_week
    • this_month
    • upcoming
  • filter[due_from]
    Type: string Format: date

    Return tasks due on or after this date.

  • filter[due_to]
    Type: string Format: date

    Return tasks due on or before this date.

  • filter[priority]
    Type: string

    One or more priorities, comma-separated or repeated.

  • filter[project_id]
    Type: string

    One or more project ids, comma-separated or repeated.

  • filter[tag_id]
    Type: string

    One or more tag ids, comma-separated or repeated.

  • filter[task_status_id]
    Type: string

    One or more task status ids, comma-separated or repeated. Returns tasks in those columns whether they are active, completed or archived.

  • filter[title]
    Type: string

    Searches task titles, ignoring case.

Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/public-api/v1/tasks
curl https://app.hellobonsai.com/public-api/v1/tasks \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "data": [
    {
      "uuid": "ad3fdad8-5072-46df-8800-bb57299179df",
      "title": "Finalize homepage mockups",
      "number": "ACME-00104",
      "due_date": "2026-05-15",
      "start_date": "2026-05-01",
      "time_estimate_in_minutes": 90,
      "priority": "high",
      "completed_at": "2026-04-14T09:12:04.000Z",
      "archived_at": "2026-04-14T09:12:04.000Z",
      "assignee_id": 6012,
      "assignee_member_id": 314,
      "creator_member_id": 315,
      "project_id": 51,
      "billable": true,
      "parent_task_uuid": "e5b1c7d2-91aa-4f30-8f6d-2c1b4a5e7f80",
      "project_title": "Acme Website",
      "assignee_member_name": "Maria Santos",
      "url": "https://app.hellobonsai.com/tasks/ad3fdad8-5072-46df-8800-bb57299179df",
      "task_status": {
        "id": "e1c4b06e-3a0f-4a52-9c8f-6a1d2b3c4d5e",
        "status": "In Progress",
        "state": "active",
        "color": "#520EB0",
        "position": 1
      },
      "company_tags": [
        {
          "id": 7,
          "name": "VIP"
        }
      ]
    }
  ],
  "meta": {
    "request_id": "b1f0d2c4-7a9e-4c3b-8d5f-1e2a3b4c5d6e",
    "pagination": {
      "page": 1,
      "page_size": 25,
      "has_more": true
    }
  }
}

A page of tasks, without their descriptions.