Monitoring & Audit

Every message relayed through Swarmd is automatically logged with full context — who sent it, which policies were evaluated, what action was taken, and how long it took. You can query these events, reconstruct full request traces, and monitor agent health.

Querying Audit Events

curl "https://api.swarmd.ai/audit/v1/events?page=0&size=20" \
  -H "Authorization: Bearer $SWARMD_TOKEN"

Available Filters

All filters are optional. Combine them to narrow your results.

Parameter	Type	Description
`startTime`	ISO 8601	Events after this time
`endTime`	ISO 8601	Events before this time
`auditType`	Enum	Filter by event type (see table below)
`transport`	Enum	`REST`, `JSONRPC`, or `GRPC`
`auditAction`	Enum	`LOG`, `MASK`, `BLOCK`, `WARN`, `HUMAN_REVIEW_REQUIRED`, or `ERROR`
`correlationId`	UUID	Events for a specific request
`sourceAgentId`	UUID	Events from a specific source agent
`sourceUserId`	UUID	Events from a specific user
`sinkAgentId`	UUID	Events targeting a specific agent
`page`	Integer	Page number (0-indexed)
`size`	Integer	Page size

Examples

Events for a specific agent in the last 24 hours:

curl "https://api.swarmd.ai/audit/v1/events?sinkAgentId=AGENT_ID&startTime=2025-03-09T00:00:00Z&page=0&size=50" \
  -H "Authorization: Bearer $SWARMD_TOKEN"

Only blocked requests:

curl "https://api.swarmd.ai/audit/v1/events?auditAction=BLOCK&page=0&size=20" \
  -H "Authorization: Bearer $SWARMD_TOKEN"

PII detection events:

curl "https://api.swarmd.ai/audit/v1/events?auditType=PRESIDIO_DETECTION&page=0&size=20" \
  -H "Authorization: Bearer $SWARMD_TOKEN"

Audit Types

Type	Description
`COMMUNICATION_AUDIT`	Standard relay message log
`VALIDATION_RESULT`	Request validation outcome
`REGEX_DETECTION`	Regex policy match
`PRESIDIO_DETECTION`	Presidio PII detection match
`COMPREHEND_DETECTION`	AWS Comprehend detection match
`RATE_LIMIT`	Rate limit policy evaluation
`SKILL_RESTRICTION`	Skill restriction policy evaluation
`HITL`	HITL policy triggered
`HITL_GUARD`	Message held for human review
`HITL_RESOLUTION`	HITL approval resolved
`POLICY_LIFECYCLE`	Policy created, updated, or disabled
`X402_PAYMENT_REQUIRED`	Payment required for request
`X402_PAYMENT_SUCCESS`	Payment completed
`X402_PAYMENT_ATTEMPT`	Payment attempted
`X402_PAYMENT_REJECTED`	Payment rejected

Tracing Requests

A trace groups all audit events for a single request using a correlationId. This lets you see the full lifecycle: incoming request, policy evaluations, relay to agent, response, and any HITL holds.

List Traces

curl "https://api.swarmd.ai/audit/v1/traces?page=0&size=20" \
  -H "Authorization: Bearer $SWARMD_TOKEN"

Traces support the same filters as events (except correlationId):

curl "https://api.swarmd.ai/audit/v1/traces?sinkAgentId=AGENT_ID&auditAction=BLOCK&page=0&size=10" \
  -H "Authorization: Bearer $SWARMD_TOKEN"

Get a Full Trace

curl https://api.swarmd.ai/audit/v1/traces/CORRELATION_ID \
  -H "Authorization: Bearer $SWARMD_TOKEN"

This returns every event associated with the request, in order:

{
  "correlationId": "abc-123-...",
  "events": [
    {
      "auditType": "COMMUNICATION_AUDIT",
      "auditAction": "LOG",
      "sentAt": "2025-03-10T14:30:00Z",
      "durationMicros": 250000,
      "sourceAgentId": "...",
      "sinkAgentId": "..."
    },
    {
      "auditType": "PRESIDIO_DETECTION",
      "auditAction": "MASK",
      "sentAt": "2025-03-10T14:30:00Z"
    }
  ]
}

Agent Health Monitoring

When you register an agent with a healthCheckUrl, Swarmd periodically checks it and tracks three health statuses:

Status	Meaning
`HEALTHY`	Agent responded with `200`
`DEGRADED`	Agent responded but with errors or slow responses
`UNHEALTHY`	Agent is not responding

View Agent Health

curl https://api.swarmd.ai/registry/v1/agents \
  -H "Authorization: Bearer $SWARMD_TOKEN"

Each agent in the response includes a healthStatus field. You can also filter to see only unhealthy agents:

curl "https://api.swarmd.ai/registry/v1/agents?healthStatus=UNHEALTHY" \
  -H "Authorization: Bearer $SWARMD_TOKEN"

What to Monitor

Here are common queries for operational monitoring:

Scenario	Query
Failed requests	`auditAction=ERROR`
Blocked by policy	`auditAction=BLOCK`
Pending human reviews	`auditType=HITL_GUARD`
HITL decisions	`auditType=HITL_RESOLUTION`
PII detections	`auditType=PRESIDIO_DETECTION`
Rate limit hits	`auditType=RATE_LIMIT`
Specific agent issues	`sinkAgentId=AGENT_ID&auditAction=ERROR`

Getting Started

Platform Management

Monitoring & Audit

Monitoring & Audit

Querying Audit Events

Available Filters

Examples

Audit Types

Tracing Requests

List Traces

Get a Full Trace

Agent Health Monitoring

View Agent Health

What to Monitor

Next Steps

Agent Discovery

Your First Agent

​Monitoring & Audit

​Querying Audit Events

​Available Filters

​Examples

​Audit Types

​Tracing Requests

​List Traces

​Get a Full Trace

​Agent Health Monitoring

​View Agent Health

​What to Monitor

​Next Steps

Agent Discovery

Your First Agent

Monitoring & Audit

Querying Audit Events

Available Filters

Examples

Audit Types

Tracing Requests

List Traces

Get a Full Trace

Agent Health Monitoring

View Agent Health

What to Monitor

Next Steps