docs: document new task endpoints

Updates `task-logs.md` document with usage examples for the new
endpoints and adds a changelog entry for the new endpoints.

PLAT-347

Author: jason-lynch

changes/unreleased/Added-20260114-162946.yaml

@@ -0,0 +1,3 @@
+kind: Added
+body: Added new API endpoints to interact with host-scoped tasks as well as an endpoint to list tasks across all scopes.
+time: 2026-01-14T16:29:46.619212-05:00

docs/using/tasks-logs.md

@@ -4,11 +4,49 @@ The pgEdge Control Plane provides tools to monitor asynchronous operations and a
 
 ## Tasks
 
-Every asynchronous database operation managed by the pgEdge Control Plane produces a *task* that you can use to track the progress of that operation.
+Every asynchronous operation managed by the pgEdge Control Plane produces a *task* that you can use to track the progress of that operation. Tasks are scoped to either a database or a host, depending on the type of operation.
 
-### Listing Tasks
+### Listing All Tasks
 
-To list tasks for a database, submit a `GET` request to the
+To list all tasks across all scopes, submit a `GET` request to the `/v1/tasks` endpoint:
+
+=== "curl"
+
+    ```sh
+    curl http://host-3:3000/v1/tasks
+    ```
+
+You can filter tasks by scope (`database` or `host`) and entity ID:
+
+=== "curl"
+
+    ```sh
+    # List only database tasks
+    curl 'http://host-3:3000/v1/tasks?scope=database'
+
+    # List tasks for a specific database
+    curl 'http://host-3:3000/v1/tasks?scope=database&entity_id=example'
+
+    # List only host tasks
+    curl 'http://host-3:3000/v1/tasks?scope=host'
+
+    # List tasks for a specific host
+    curl 'http://host-3:3000/v1/tasks?scope=host&entity_id=host-1'
+    ```
+
+This endpoint also supports pagination and sorting:
+
+=== "curl"
+
+    ```sh
+    curl 'http://host-3:3000/v1/tasks?limit=10&after_task_id=404ecbe0-5cda-11f0-900b-a74a79e3bdba&sort_order=asc'
+    ```
+
+## Database Tasks
+
+### Listing Database Tasks
+
+To list tasks for a specific database, submit a `GET` request to the
 `/v1/databases/{database_id}/tasks` endpoint. For example:
 
 === "curl"
@@ -68,6 +106,58 @@ You can also limit your request to only the most recent log entries with the
     curl 'http://host-3:3000/v1/databases/example/tasks/d3cd2fab-4b1f-4eb9-b614-181c10b07acd/log?limit=10'
     ```
 
+## Host Tasks
+
+Some operations, such as removing a host from the cluster, produce tasks scoped to a host rather than a database.
+
+### Listing Host Tasks
+
+To list tasks for a specific host, submit a `GET` request to the
+`/v1/hosts/{host_id}/tasks` endpoint:
+
+=== "curl"
+
+    ```sh
+    curl http://host-3:3000/v1/hosts/host-1/tasks
+    ```
+
+This endpoint supports the same pagination and sorting options as the database tasks endpoint:
+
+=== "curl"
+
+    ```sh
+    curl 'http://host-3:3000/v1/hosts/host-1/tasks?limit=5&after_task_id=404ecbe0-5cda-11f0-900b-a74a79e3bdba&sort_order=asc'
+    ```
+
+### Getting a Specific Host Task
+
+To fetch details for a specific host task, submit a `GET` request to the `/v1/hosts/{host_id}/tasks/{task_id}` endpoint:
+
+=== "curl"
+
+    ```sh
+    curl http://host-3:3000/v1/hosts/host-1/tasks/d3cd2fab-4b1f-4eb9-b614-181c10b07acd
+    ```
+
+### Getting Host Task Logs
+
+You can fetch log messages for a host task by submitting a `GET` request to the
+`/v1/hosts/{host_id}/tasks/{task_id}/logs` endpoint:
+
+=== "curl"
+
+    ```sh
+    curl http://host-3:3000/v1/hosts/host-1/tasks/d3cd2fab-4b1f-4eb9-b614-181c10b07acd/logs
+    ```
+
+The same pagination options (`after_entry_id` and `limit`) are supported:
+
+=== "curl"
+
+    ```sh
+    curl 'http://host-3:3000/v1/hosts/host-1/tasks/d3cd2fab-4b1f-4eb9-b614-181c10b07acd/logs?limit=10'
+    ```
+
 ## Viewing Postgres Logs
 
 By default, each database is configured to write log files to the following directory: