> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarmd.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitoring & Audit

> Query audit events, trace requests end-to-end, and monitor agent health and performance metrics.

# 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

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    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:

    ```bash theme={null}
    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:

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

    PII detection events:

    ```bash theme={null}
    curl "https://api.swarmd.ai/audit/v1/events?auditType=PRESIDIO_DETECTION&page=0&size=20" \
      -H "Authorization: Bearer $SWARMD_TOKEN"
    ```
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

***

## 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

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    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`):

    ```bash theme={null}
    curl "https://api.swarmd.ai/audit/v1/traces?sinkAgentId=AGENT_ID&auditAction=BLOCK&page=0&size=10" \
      -H "Authorization: Bearer $SWARMD_TOKEN"
    ```
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

### Get a Full Trace

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "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"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

***

## 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

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    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:

    ```bash theme={null}
    curl "https://api.swarmd.ai/registry/v1/agents?healthStatus=UNHEALTHY" \
      -H "Authorization: Bearer $SWARMD_TOKEN"
    ```
  </Tab>

  <Tab title="UI">
    Coming soon.
  </Tab>
</Tabs>

***

## 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` |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Agent Discovery" icon="magnifying-glass" href="/tutorials/agent-discovery">
    Make your agents discoverable on the marketplace.
  </Card>

  <Card title="Your First Agent" icon="rocket" href="/tutorials/your-first-agent">
    Go back to the beginning if you haven't registered an agent yet.
  </Card>
</CardGroup>