Manual pagination query endpoints for jobs, logs and traces

CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-05-20
+
+### Added
+
+- `workflows`: Added cursor and limit query options plus `QueryPage`, `QueryLogsPage`, and `QuerySpansPage` for manual pagination of job, log, and span queries.
+- `workflows`: Added `job.WithTaskStates(...)` to filter job queries by task state.
+- `workflows`: Added string and JSON representations for job and task states.
+
+### Changed
+
+- `workflows`: Changed job, log, and span queries to support cursor-based pagination while keeping existing sequence APIs auto-paginated.
+- `workflows`: Moved telemetry query options to the `workflows/v1/job` package so job and telemetry queries share `job.WithLimit`, `job.WithCursor`, and `job.WithSortDirection`.
+
 ## [0.5.0] - 2026-05-11
 
 ### Added
@@ -90,7 +103,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added support for Tilebox Observability, including logging and tracing helpers.
 - Added examples for using the library.
 
-[Unreleased]: https://github.com/tilebox/tilebox-go/compare/v0.5.0...HEAD
+[Unreleased]: https://github.com/tilebox/tilebox-go/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/tilebox/tilebox-go/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/tilebox/tilebox-go/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/tilebox/tilebox-go/compare/v0.3.2...v0.4.0
 [0.3.2]: https://github.com/tilebox/tilebox-go/compare/v0.3.1...v0.3.2

README.md

@@ -162,6 +162,41 @@ func main() {
 }
 ```
 
+### Querying Job Telemetry
+
+After a job has been executed, we can query runner logs associated with it.
+
+```go
+package main
+
+import (
+	"context"
+	"log/slog"
+
+	"github.com/google/uuid"
+	"github.com/tilebox/tilebox-go/workflows/v1"
+	"github.com/tilebox/tilebox-go/workflows/v1/job"
+)
+
+func main() {
+	ctx := context.Background()
+	client := workflows.NewClient()
+	jobID := uuid.MustParse("019e070c-63ba-1c7e-5f1d-65be3e22d52a")
+
+	for logRecord, err := range client.Jobs.QueryLogs(ctx, jobID,
+		job.WithLimit(100),
+		job.WithSortDirection(job.Ascending),
+	) {
+		if err != nil {
+			slog.ErrorContext(ctx, "failed to query job logs", slog.Any("error", err))
+			return
+		}
+
+		slog.InfoContext(ctx, "job log", slog.String("body", logRecord.Body))
+	}
+}
+```
+
 ## License
 
 Distributed under the MIT License (`The MIT License`).

examples/workflows/observability/query/main.go

@@ -8,6 +8,7 @@ import (
 
 	"github.com/google/uuid"
 	"github.com/tilebox/tilebox-go/workflows/v1"
+	"github.com/tilebox/tilebox-go/workflows/v1/job"
 )
 
 func main() {
@@ -18,7 +19,7 @@ func main() {
 
 	fmt.Println("Log messages:")                             //nolint:forbidigo // This example intentionally prints query results to stdout.
 	fmt.Printf("%-8s  %-30s  %s\n", "LEVEL", "TIME", "BODY") //nolint:forbidigo // This example intentionally prints query results to stdout.
-	for logRecord, err := range client.Jobs.QueryLogs(ctx, jobID, workflows.WithSortDirection(workflows.Ascending)) {
+	for logRecord, err := range client.Jobs.QueryLogs(ctx, jobID, job.WithSortDirection(job.Ascending)) {
 		if err != nil {
 			slog.ErrorContext(ctx, "failed to query job logs", slog.Any("error", err))
 			return