ticket.search

Filtered, paginated ticket list with optional best-effort live source hydration.

Overview

Property	Value
Workflow type	Atomic
Library	App-tickets
Version	1.0

Input Schema

Field	Type	Required	Default	Description
organization_uuid	string	Yes	—	Organization whose tickets are searched; injected from context.
status	list	No	—	Ticket status. Values: open, triaged, in_progress, blocked, resolved, closed, ignored.
priority	list	No	—	Priority. Canonical values: page, priority, routine, deferred. Accepted aliases: urgent->page, high->priority, medium->routine, low->deferred.
kind	list	No	—	Ticket kind. Values: incident, task, info.
source_type	list	No	—	Ticket provenance. Values: lumen_error_group, actor_finding, alert_rule, audit_finding, tool_request, workflow_run, human, api, linear.
severity	list	No	—	Impact severity. Values: critical, high, medium, low, info.
subject_type	string	No	—	Exact ecosystem subject-type filter.
subject_uuid	string	No	—	Exact public subject UUID filter.
assignee_uuid	string	No	—	Exact assignee UUID filter.
unassigned	boolean	No	—	When true, return only tickets with no assignee. Mutually exclusive with assignee_uuid.
owner_uuid	string	No	—	Exact creator/owner UUID filter.
labels	list	No	—	Require tickets matching the supplied labels.
exclude_labels	list	No	—	Drop tickets carrying ANY of the supplied labels. Use this to skip already-claimed work in the query instead of filtering the page after it is returned — e.g. exclude_labels=['triage-claimed'].
chain_uuid	string	No	—	Exact workflow correlation-chain UUID filter.
q	string	No	—	Case-insensitive free-text search over ticket content.
updated_since	datetime	No	—	Return tickets updated at or after this ISO-8601 timestamp.
updated_before	datetime	No	—	Return tickets updated strictly before this ISO-8601 timestamp.
created_after	datetime	No	—	Return tickets created at or after this ISO-8601 timestamp.
created_before	datetime	No	—	Return tickets created strictly before this ISO-8601 timestamp.
last_seen_after	datetime	No	—	Return tickets last-seen at or after this ISO-8601 timestamp.
last_seen_before	datetime	No	—	Return tickets last-seen strictly before this ISO-8601 timestamp.
sort	string	No	—	Sort key. Values: priority (ticket.search default; page > priority > routine > deferred), last_seen_at, created_at. Direction is controlled by order (time sorts default newest-first; priority defaults page-first).
order	string	No	—	Sort direction: asc or desc. Defaults preserve prior behaviour — desc for last_seen_at/created_at (newest first), asc for priority (page first).
limit	integer	No	—	Maximum page size; defaults to 50 and is server bounded.
cursor	string	No	—	Opaque keyset cursor returned by the previous page.
include_total	boolean	No	—	When true, also return the filter-matched row count as total. Defaults false so list latency stays unchanged.
hydrate	boolean	No	—	Attach best-effort live source state to each item; defaults false.
include_body	boolean	No	—	When true, each item includes the full ticket body and resolution. Defaults false so list latency stays bounded; use ticket.get for the body of the ticket being worked.

Output Schema

Field	Type	Required	Default	Description
items	list	No	—	Ticket rows matching the filters in requested sort order. List projection omits body and resolution; use ticket.get for the full body of a single ticket.
next_cursor	string	No	—	Opaque cursor for the next page, or null when exhausted.
total	integer	No	—	Filter-matched ticket count when include_total=true; otherwise null. Stable across pages (counted before cursor/limit).
lifecycle	dict	No	—	Statuses, priority choices, aliases, and allowed transition map.
error	string	No	—	Error-as-field envelope populated when query() raises.
error_type	string	No	—	Error-as-field envelope populated when query() raises.

States

State	Initial	Terminal	Success	Auto-advance	Description
done	Yes	Yes	Yes	—	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "ticket.search",
  "initial_data": {
    "organization_uuid": "value"
  }
}