Skip to main content

​
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.
ParameterTypeDescription
startTimeISO 8601Events after this time
endTimeISO 8601Events before this time
auditTypeEnumFilter by event type (see table below)
transportEnumREST, JSONRPC, or GRPC
auditActionEnumLOG, MASK, BLOCK, WARN, HUMAN_REVIEW_REQUIRED, or ERROR
correlationIdUUIDEvents for a specific request
sourceAgentIdUUIDEvents from a specific source agent
sourceUserIdUUIDEvents from a specific user
sinkAgentIdUUIDEvents targeting a specific agent
pageIntegerPage number (0-indexed)
sizeIntegerPage 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

TypeDescription
COMMUNICATION_AUDITStandard relay message log
VALIDATION_RESULTRequest validation outcome
REGEX_DETECTIONRegex policy match
PRESIDIO_DETECTIONPresidio PII detection match
COMPREHEND_DETECTIONAWS Comprehend detection match
RATE_LIMITRate limit policy evaluation
SKILL_RESTRICTIONSkill restriction policy evaluation
HITLHITL policy triggered
HITL_GUARDMessage held for human review
HITL_RESOLUTIONHITL approval resolved
POLICY_LIFECYCLEPolicy created, updated, or disabled
X402_PAYMENT_REQUIREDPayment required for request
X402_PAYMENT_SUCCESSPayment completed
X402_PAYMENT_ATTEMPTPayment attempted
X402_PAYMENT_REJECTEDPayment 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:
StatusMeaning
HEALTHYAgent responded with 200
DEGRADEDAgent responded but with errors or slow responses
UNHEALTHYAgent 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:
ScenarioQuery
Failed requestsauditAction=ERROR
Blocked by policyauditAction=BLOCK
Pending human reviewsauditType=HITL_GUARD
HITL decisionsauditType=HITL_RESOLUTION
PII detectionsauditType=PRESIDIO_DETECTION
Rate limit hitsauditType=RATE_LIMIT
Specific agent issuessinkAgentId=AGENT_ID&auditAction=ERROR

​
Next Steps

Agent Discovery

Make your agents discoverable on the marketplace.

Your First Agent

Go back to the beginning if you haven’t registered an agent yet.