List events

Restrict to events that stand for one discovery run. That is the union of two sets: every event the run itself has written — all of them, whatever their eventDate, because a job change is dated by the month the job STARTED and can predate the lookback — and the canonical events that match its accounts, its signals and the event-date window from startedAt - lookbackDays through settledAt, including ones an earlier run wrote. So the page can be non-empty when the run reports eventsNew: 0, and a settled run paged to the end — follow nextCursor until hasMore is false — yields at least eventsNew events, which one page of at most 100 need not; the run counters remain about that execution. Before the run settles this returns what it has written so far — poll for the rest. Additional account, signal, or date filters only narrow this scope. Use the id from POST/GET /v1/discoveries; a run that does not resolve in your workspace is a 404 (discovery_run_not_found). One limit worth knowing: the out-of-window half covers what THIS run wrote. An event an earlier run wrote outside this run's window, and that this run merely re-detected, is matched to that earlier row and stays outside — read it by accountId and signalKey instead.

Restrict to events on one account.

Restrict to events matched to this signal.

Restrict to events matched to ANY of these signals — the union, not the intersection. A check of several signals needs one call rather than one per key. Pair it with discoveredSince to read events found after your previous check. Send this or signalKey, not both.

Send a plain date — 2026-06-07, read as midnight UTC — or a full ISO-8601 timestamp — 2026-06-07T14:30:00Z — when you need the time of day. Relative words are not accepted: yesterday, last-quarter, 7d and anything else that has to be resolved against "now" is rejected with a 400 (invalid_date). Compute the date yourself and send it. Only events that HAPPENED at or after this value — eventDate, the date carried by the event itself. Ask it when the age of what happened is what matters to you.

For events found after your previous check, use discoveredSince instead. An article published last month can reach your workspace today, and this filter will not show it to you.

Send a plain date — 2026-06-07, read as midnight UTC — or a full ISO-8601 timestamp — 2026-06-07T14:30:00Z — when you need the time of day. Relative words are not accepted: yesterday, last-quarter, 7d and anything else that has to be resolved against "now" is rejected with a 400 (invalid_date). Compute the date yourself and send it. Only events Trayo FOUND at or after this value — createdAt on every row, and the order this list already comes back in.

Use this to read events found since your previous check. Send the moment you last looked and you get everything new since then, whatever date the events themselves carry — news that happened before the previous check included. since answers the other question, when the event happened; send both and an event has to satisfy both.

Defaults to live — dismissed events are excluded unless you ask for them.

dismissed is Trayo's own verdict, not yours: an event discovery produced and then withdrew. Nothing a caller does moves an event into it, so it is normally empty for a workspace whose events all come from this API. It stays readable with ?state=dismissed.

To dismiss an event yourself, send DELETE /v1/events/{id} — the same action as the dismiss button in the Trayo app. Nothing a discovery run wrote is permanent. An event dismissed that way does not turn up under ?state=dismissed: it leaves both states, its id 404s afterwards, and it stays gone, because discovery deduplicates against every event in the workspace, the ones you dismissed included, so no later run recreates it.

So the two readable states answer different questions: live is what stands, dismissed is what Trayo withdrew, and what you dismissed is in neither.

Send expand=people,signals to add the people and signals arrays to every item in data. Despite the comma-separated syntax, expansion is currently ALL-OR-NOTHING: any non-empty value — people alone, signals alone, even expand=bogus — expands both fields together. There is no way to request only one. Omit the parameter entirely for the compact form.

Opaque pagination cursor from a previous page's nextCursor. Omit for the first page. Do not construct or parse this value — it is a base64url-encoded implementation detail and may change shape without notice.

Page size, default 25. Values above 100 are silently CAPPED to 100, not rejected. Note the deliberate contrast with the two other bounds in this API: POST /v1/find's limit is rejected above 100 (and a sentence search returns at most 50), and a /v1/…/batch array of more than 200 items is an ERROR rather than a clamp — silently dropping rows would lose records the caller believes it created. A limit that is zero, negative or not an integer is rejected here too; only the upper bound clamps.