GET /api/v1/processes

List & Get Processes

List Processes

curl "https://your-instance/api/v1/processes?status=running&search=deploy&sort=newest&limit=10" \
  -H "Authorization: Bearer htk_..."

Query Parameters

Parameter	Type	Default	Description
`status`	string	—	Filter: `running`, `completed`, `failed`
`namespace`	string	—	Filter by namespace
`search`	string	—	Search processes by name (substring match)
`sort`	string	`newest`	Sort order by start date: `newest` or `oldest`
`limit`	number	50	Page size (1-200)
`offset`	number	0	Pagination offset

All filter parameters can be combined in a single request.

Response

{
	"processes": [
		{
			"process_id": "uuid",
			"namespace": "orgId.deployments",
			"name": "Deploy v2.1.0",
			"status": "running",
			"current_step": "test",
			"started_at": "2026-02-24T12:00:00Z",
			"step_count": 5,
			"task_ids": ["task-uuid-1"]
		}
	],
	"total": 15,
	"limit": 10,
	"offset": 0
}

Get Process

curl https://your-instance/api/v1/processes/proc-uuid \
  -H "Authorization: Bearer htk_..."

Response

Returns the full process with step definitions and timeline:

{
	"process_id": "proc-uuid",
	"namespace": "orgId.deployments",
	"name": "Deploy v2.1.0",
	"status": "running",
	"current_step": "test",
	"step_defs": [
		{ "key": "build", "label": "Build", "human": false },
		{ "key": "test", "label": "Test", "human": false },
		{ "key": "review", "label": "Review", "human": true }
	],
	"timeline": [
		{
			"step": "build",
			"label": "Build",
			"status": "completed",
			"human": false,
			"started_at": "2026-02-24T12:00:00Z",
			"completed_at": "2026-02-24T12:02:00Z",
			"duration_ms": 120000,
			"detail": "Build successful"
		},
		{
			"step": "test",
			"label": "Test",
			"status": "running",
			"human": false,
			"started_at": "2026-02-24T12:02:00Z",
			"progress_message": "Running integration tests...",
			"progress_percent": 65
		},
		{
			"step": "review",
			"label": "Review",
			"status": "pending",
			"human": true,
			"task_id": "task-uuid-1"
		}
	],
	"task_ids": ["task-uuid-1"],
	"started_at": "2026-02-24T12:00:00Z"
}

Errors

Status	Meaning
`401`	Missing or invalid token
`404`	Process not found or belongs to a different organization