list_signals
What has changed on this map, as typed events with a severity, the objects they concern and a payload of counts and structure. This is the pulse: poll it to find work rather than re-reading the whole map — a finding that appeared or went away, a finding whose status a human moved, a process step that now takes twice as long, a process that stopped running altogether. The conditions the workspace wrote itself as rules land here too, judged per group by every scan as it finishes: rule_fired while a group matches, rule_cleared once it stops, rule_broken when the map can no longer answer the rule. A rule's first evaluation is its baseline and raises nothing, so a group reaches you when it starts holding, or stops holding and later holds again. When a workspace admin makes an older scan the current map again, one map_rolled_back signal says so: the map you built on changed by a person's decision, not in the customer's systems, so re-read before you act on what you learned from it (only a key that sees the whole map is sent it). A scan that met file or folder names that look like CPR numbers raises one cpr_file_names signal with the count, never the names: Maplith tries to mask those numbers in the map, and the customer may want to rename the files (also only for a key that sees the whole map). A signal is raised only when an agent has to handle it: a queue of similar items one agent works through in one pass is one signal with count and items in its payload, closed when the queue is empty. Every signal has a state — open (nobody has picked it up), planned (someone picked it up for later: planned says by you, another_agent or a_person, since when and due when, and overdue once past its date), in_progress (an agent holds it on a lease, or it waits on a person) or done, with a resolution (fixed, not_an_issue, wont_fix; or Maplith's own: resolved_itself when the check that raised it found the condition gone before anyone recorded a fix or a close — whether nobody had taken it or it was waiting on a person who had not taken it up, notice for news that asks nothing, unstated for a close recorded before resolutions existed) — plus episode, held (you, another_agent, a_person) and, for a signal that came back, previous. Filter with since (an ISO timestamp from a previous call), kinds, exclude_kinds, states and unacted; page with limit and the returned next_cursor. To review a whole queue, read the counts the first page carries (every signal you may see, by kind and state; a key limited to part of the map gets none) and exclude the kinds you are not reviewing; for counts over a period — raised, acted on, by outcome — call get_value_summary rather than paging. since compares created_at, which only a scan (or a person changing a finding's status) moves: a signal that goes back to open without one (a hold that ran out, a person who let it go or reopened it) keeps its created_at, so read the queue with states ['open'] and no since. The kinds that ask nothing are born done, so read news such as map_rolled_back with since and no state filter. A finding_added resolves itself when a later scan no longer reports the finding. A routine your human put on a schedule (a playbook that runs "every Monday at 07:30") raises one routine_due signal each time it falls due, naming that playbook in its payload: get_task_context hands you exactly that playbook, and record_action closes that occurrence (the next one is raised on its own; one nobody took is closed when the next is raised, which says since when it was missed). Payloads carry aggregates and structure, not rows. Follow a signal up with get_task_context, take it with take_signal before you work on it (or plan it for later with take_signal and plan: true, where planning is offered), and report with record_action.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kinds | No | ||
| limit | No | Signals per page. Default 100; up to 500 for a key that sees the whole map, up to 100 for a key limited to part of it. | |
| since | No | ISO 8601 timestamp — only signals created after it. | |
| cursor | No | The next_cursor from the previous call. | |
| states | No | Only signals in these states, as your key sees them. open is open and not picked up; planned is open and planned by someone. | |
| unacted | No | Only signals still to be dealt with: open, planned or in_progress (including ones another agent holds or that wait on a person). For only the work nobody has picked up, pass states: ["open"] instead. For a key limited to part of the map, a close counts only when that key may see the record behind it: one made without the signal's current version, or while the signal named objects outside the key, does not, so such a signal still comes back as open. | |
| exclude_kinds | No | Leave these kinds out, e.g. ['setup_gap'] when you review findings. |