Inspect Tasks and Workers

Find out what a Task is doing, why it failed, and whether its Worker had enough CPU and memory. Spiral Studio shows each Attempt's progress, its error, and its Worker's resource use, and the Task API returns the same data, so your application can show it too.

PrerequisitesCopy Anchor Link

• You have the Project viewer role.

Find Task runsCopy Anchor Link

In Studio, open Tasks, then View all runs.

• Select Type to show one Task specification across all its versions. Select All types to remove this filter.
• Use Find a Task to search by operation name or Task ID. Search ignores letter case and covers the full run history.
• The Runs view also filters by status, by origin (manual, event, or schedule), and by Worker Pool.
• Select Load more runs to see more results.

The Duration column shows live elapsed time from the Task's first Attempt, including retries and time between Attempts. It updates every second while the Task is unfinished and stops when the Task finishes. The Updated line shows how recently the Task record changed. Open a Task to see the duration of each Attempt separately.

Over HTTP, GET /api/tasks/projects/{project_id}/tasks accepts the same filters: taskSpecName, query, status, origin, and workerPoolId. See Follow the status.

Find the Tasks of a ResourceCopy Anchor Link

The workspace of a Resource has a Tasks tab. By default, it shows the Tasks that target the Resource, across branches and versions. Select All related tasks to also include Tasks that use the Resource as a source or a dependency.

Each Task page lists the Resources that its input names, with their roles and recorded versions. Each link opens the Resource at the recorded commit, or at the current head of the recorded branch.

For keyed table maintenance and flush Tasks, the target link opens the live table. If the table is unavailable, Studio shows its ID.

Over HTTP, pass resourceId, and optionally resourceRole (target, source, dependency, or source_location):

curl "https://api.spiraldb.dev/api/tasks/projects/demo/tasks?resourceId=$TABLE_RESOURCE_ID&resourceRole=target" \
  -H "Authorization: Bearer $SPIRAL_TOKEN"

Follow keyed table maintenanceCopy Anchor Link

During deletion application, the progress shows how many fragments the Task has checked, changed, or skipped. These counts measure fragments, not bytes or time. A large fragment can take longer than many small fragments.

The Task checks fragments concurrently within its configured memory budget. It leaves unaffected fragments in place and removes fully deleted fragments without rewriting their values. It publishes a deletion checkpoint after the entire column group is complete, then flushes the write-ahead log before the next group.

See why a Task failedCopy Anchor Link

Read the Task with GET /api/tasks/{task_id}. A failed Task has a failure with three fields:

Each Attempt in attempts has its own status and failure, so you can see whether every Attempt failed the same way or a later one failed differently. A cancelled Task has a cancellationReason instead: user when someone cancelled it, pending_timeout when no Worker claimed it within six hours, or parent_cancelled or parent_failed for a child Task whose parent stopped.

In Studio, the Task page shows the same failure and the failure of each Attempt.

Follow execution progressCopy Anchor Link

Open a Task in Studio to see the current operation of its active Attempt. All built-in Task specifications report progress. When an operation has a known total, Studio shows the completed operations and a percentage for that stage. Other stages show an activity indicator. A stage can reach 100% while later stages remain. The Task is complete only when its status is succeeded.

For legacy Table maintenance that uses parallel workers, Studio reports how many child Tasks have been submitted and how many have succeeded in the current compaction pass. Maintenance saves their combined output after the workers finish.

Workers report progress every five seconds. A retry starts its own progress from zero, and failed and cancelled Attempts keep the last report Spiral received, so you can see how far they got.

The Capacity field shows the Worker session that ran the latest Attempt. Spiral-managed sessions show the Auto worker label. Each Attempt links to its Worker page.

Read resource usageCopy Anchor Link

The Worker page shows CPU and memory for the last hour of the session. Each Attempt has a separate chart for its full duration.

• CPU usage is in cores, next to the available capacity.
• Memory usage is in bytes, next to the container limit when it is known. The memory chart keeps the highest value in each interval.
• Dashed lines show Worker capacity or a container limit. Amber lines show Task requests and Attempt boundaries. Task requests are scheduling minimums, not enforced limits.

Workers sample resources each second. In a container, the measurements cover everything the Worker runs. Outside a container they are estimates, and memory shared between processes can be counted more than once. If a Worker sends no report for 15 seconds, its samples go stale and the charts show a gap.

Read the same data over HTTP. Pass attemptId to select one Attempt:

curl https://api.spiraldb.dev/api/tasks/projects/demo/worker-sessions/$WORKER_SESSION_ID/resource-usage \
  -H "Authorization: Bearer $SPIRAL_TOKEN"

A Worker that stops abruptly cannot report its final usage, so a memory peak alone does not prove that it ran out of memory. Check the platform that ran the Worker to confirm it, for example with kubectl describe pod on Kubernetes. If it did, submit the Task again with a larger resource profile.

List Workers and their AttemptsCopy Anchor Link

curl "https://api.spiraldb.dev/api/tasks/projects/demo/worker-sessions?status=active" \
  -H "Authorization: Bearer $SPIRAL_TOKEN"

curl https://api.spiraldb.dev/api/tasks/projects/demo/worker-sessions/$WORKER_SESSION_ID/attempts \
  -H "Authorization: Bearer $SPIRAL_TOKEN"

A Worker session status is active, draining, or expired. The Attempt list contains only the Attempts that this Worker ran. Each Attempt links to its Task, even when another Worker completed the Task later.

Where next: add Worker capacity when Tasks wait too long.