Observability

Event reference

The event envelope, every event type, severity mapping per destination, and the pull and streaming APIs.

Envelope

Every event — in the pull API, the stream, the CLI and every destination — has the same shape. Destinations wrap it in their own format (Splunk event, Datadog log attributes, OTLP log record attributes, webhook { events: [...] }).

Field	Type	Description
`id`	integer (string in cursors)	Stable, increasing id. Dedupe and resume with it.
`tenant_id`	UUID	Workspace
`occurred_at`	ISO 8601	When the change happened
`type`	string	Dotted type, e.g. `workflow.run.failed`
`category`	`workflow` · `integration` · `agent` · `audit` · `security` · `task` · `system`	Grouping used by filters and permissions
`severity`	`debug` · `info` · `warn` · `error`	Normalised severity
`message`	string (≤ 1000 chars)	One-line summary
`source_table`, `source_id`	string	Where the event came from
`trace_id`, `run_id`, `workflow_id`, `task_id`, `actor_id`	UUID or null	Correlation. `trace_id` links a run with its integration calls and agent runs.
`attributes`	object	Allow-listed details: status, duration_ms, host, path, model, token counts, changed field names…

Example

{
  "id": 48213,
  "tenant_id": "6f1c…",
  "occurred_at": "2026-10-24T09:14:03.512Z",
  "type": "integration.call",
  "category": "integration",
  "severity": "warn",
  "message": "POST api.example.com/v1/orders → 429 in 812ms",
  "source_table": "integration_call_logs",
  "source_id": "b0a4…",
  "trace_id": "9d2e…", "run_id": "1c7f…", "workflow_id": "a83b…", "task_id": null, "actor_id": null,
  "attributes": { "method": "POST", "host": "api.example.com", "path": "/v1/orders", "status": 429, "duration_ms": 812 }
}

Event types

Filter with exact types or globs (* matches within a segment): workflow.run.*, *.failed, security.*.

Type	Category	Severity	When
`workflow.run.started` / `resumed` / `waiting` / `paused` / `completed`	workflow	info	A run changes status (`duration_ms` on completion)
`workflow.run.failed`	workflow	error	A run failed
`workflow.run.cancelled`	workflow	warn	A run was cancelled
`workflow.run.sla_warning` / `sla_breached`	workflow	warn / error	A run approaches or breaches its SLA
`workflow.step.log`	workflow	from the log level	One per step log line (turn off with `settings.event_stream.include_step_logs = false`)
`workflow.queue.failed` / `dead`	workflow	warn / error	A queued job failed and will retry / gave up
`integration.call`	integration	info; warn on 4xx; error on 5xx	Every outbound call: method, host, path, status, duration
`integration.webhook.dead_letter`	integration	error	An outbound webhook was dead-lettered
`agent.run.<status>`	agent	error when failed, else info	Agent runs: model, token counts, duration
`audit.<object_type>.<action>`	audit	info	Any audited change, with changed field names
`security.oauth.token_issued` / `token_revoked` / `code_replay` / `refresh_reuse`	security	info; warn for replay and reuse	OAuth token lifecycle
`security.api_key.<action>` / `security.api_key.auth_failed`	security	info; warn for failures	API key lifecycle and sampled failures
`security.permission.<action>`	security	info	Role and permission changes
`system.retention.purged` / `purge_failed` / `review_*`	system	info / error	Retention executions and reviews
`system.deletion.completed` / `failed`	system	info / error	Queued deletions
`system.sync.github.` / `system.sync.directory.`	system	info / error	Sync runs
`system.log_export.data_lost`	system	warn	A destination fell behind retention
`system.test`	system	info	"Send test event" (never stored)
`task.<event_type>`	task	warn for escalated / blocked / rejected, else info	Task lifecycle

Severity mapping

UserTasks	Splunk `severity`	Datadog `status`	OTLP severityNumber / Text
debug	debug	debug	5 / DEBUG
info	info	info	9 / INFO
warn	warn	warning	13 / WARN
error	error	error	17 / ERROR

Workflow step log levels map trace → debug, warning → warn and fatal → error.

Pull API

bash

curl -H "Authorization: Bearer $USERTASKS_API_KEY" "$USERTASKS_URL/api/v1/events?since=1h&category=workflow&limit=500"
# → { "events": [...], "next_cursor": "48213", "has_more": true }
curl -H "Authorization: Bearer $USERTASKS_API_KEY" "$USERTASKS_URL/api/v1/events?after=48213&limit=500"

Filters: category, type (globs), severity (minimum), workflow_id, run_id, task_id, trace_id, since.

Live stream (Server-Sent Events)

bash

curl -N -H "Authorization: Bearer $USERTASKS_API_KEY" -H "Last-Event-ID: 48213" \
  "$USERTASKS_URL/api/v1/events/stream?severity=warn"
# id: 48214
# event: workflow.run.failed
# data: {"id":48214,"type":"workflow.run.failed",...}
# : heartbeat            (every 15 s when idle)
# event: reconnect       (before the server's time limit; resume with the last id)

Each message is named after its event type, so browser EventSource clients add a listener per type; curl, the SDK and the CLI see every message.
The stream resumes from Last-Event-ID (or ?after=); without either it starts at the newest event, or at since=.
On serverless hosts the response ends at the function limit with an event: reconnect hint; the SDK and usertasks logs tail reconnect without gaps.
The stream accepts API keys and OAuth tokens, not browser sessions.