Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.adrian.secureagentics.ai/llms.txt

Use this file to discover all available pages before exploring further.

Secureagentics gives you visibility into everything your AI agents do. You can browse and filter events in the dashboard, correlate related events across a single request trace, query events programmatically, and review automatically detected anomalies and compliance audit logs.

​
Events timeline

The Events timeline is the central monitoring view in the Secureagentics dashboard. Open it by navigating to Monitoring → Events. The timeline shows a chronological stream of every event received from your registered agents. Each row displays:
  • The event type (prompt, completion, tool_call, error)
  • The agent that sent the event
  • The timestamp
  • The trace_id (if provided)
  • The policy outcome (allowed, blocked, or pending)

​
Filter the timeline

Use the filter bar at the top of the Events page to narrow the view:
FilterHow to use
AgentSelect one or more agents from the dropdown to show only their events.
Time rangeSet a start and end date/time, or choose a preset such as “Last 1 hour” or “Last 24 hours”.
Event typeCheck one or more event types to include (prompt, completion, tool_call, error).
Trace IDEnter a trace_id to show only events belonging to a single request trace.
Bookmark a filtered URL after applying filters. The Secureagentics dashboard preserves filter state in the URL query string, so you can share a pre-filtered view with teammates.

​
Request tracing

Request tracing lets you follow a single end-to-end agent interaction across multiple events. When your agent code assigns a shared trace_id to all events from one request, Secureagentics links those events together.

​
How it works

  1. At the start of each user request or agent run, generate a unique ID (a UUID is recommended).
  2. Pass that ID as the trace_id field on every event emitted during that run.
  3. In the dashboard, enter the trace_id in the filter bar to see all events from that run in sequence.
1

Generate a trace ID in your agent

import uuid
import requests

trace_id = str(uuid.uuid4())  # e.g. "b3d2e1f0-9a8b-4c7d-8e6f-1a2b3c4d5e6f"

API_KEY = "your_api_key_here"
AGENT_ID = "agt_01hx9z3k2m4n5p6q7r8s9t0u"
BASE_URL = "https://api.secureagentics.ai/v1"

def send_event(event_type, payload):
    requests.post(
        f"{BASE_URL}/agents/{AGENT_ID}/events",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={"type": event_type, "payload": payload, "trace_id": trace_id},
    ).raise_for_status()

# All three events are linked by the same trace_id
send_event("prompt", {"text": "Summarize this document"})
send_event("tool_call", {"tool": "read_file", "input": {"path": "/docs/report.pdf"}})
send_event("completion", {"text": "The document covers...", "tokens_used": 450})
2

View the trace in the dashboard

In Monitoring → Events, paste your trace_id into the Trace ID filter. You will see all events from that run, ordered by timestamp, with timing gaps between them.

​
Fetch events via API

You can query agent events programmatically using the GET /v1/agents/{id}/events endpoint.

​
Query parameters

ParameterTypeDescription
limitintegerMaximum number of events to return. Default: 50. Maximum: 500.
offsetintegerNumber of events to skip for pagination. Default: 0.
typestringFilter by event type: prompt, completion, tool_call, or error.
fromstringISO 8601 start timestamp (inclusive).
tostringISO 8601 end timestamp (inclusive).
import requests

API_KEY = "your_api_key_here"
AGENT_ID = "agt_01hx9z3k2m4n5p6q7r8s9t0u"
BASE_URL = "https://api.secureagentics.ai/v1"

# Fetch the last 100 error events from the past hour
response = requests.get(
    f"{BASE_URL}/agents/{AGENT_ID}/events",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={
        "type": "error",
        "limit": 100,
        "from": "2026-05-04T09:00:00Z",
        "to": "2026-05-04T10:00:00Z",
    },
)

response.raise_for_status()
events = response.json()["events"]
print(f"Found {len(events)} error events")
for event in events:
    print(event["id"], event["created_at"], event["payload"])
The response is a paginated object: 
{
  "events": [
    {
      "id": "evt_09jk2l3m4n5o6p7q",
      "agent_id": "agt_01hx9z3k2m4n5p6q7r8s9t0u",
      "type": "error",
      "trace_id": "b3d2e1f0-9a8b-4c7d-8e6f-1a2b3c4d5e6f",
      "payload": { "message": "Upstream API timeout", "code": "ETIMEDOUT" },
      "created_at": "2026-05-04T09:42:11Z"
    }
  ],
  "total": 3,
  "limit": 100,
  "offset": 0
}
Use offset and limit together to paginate through large result sets. For example, to retrieve events 101–200, set offset=100&limit=100.

​
Anomaly detection

Secureagentics continuously analyzes event streams and automatically flags unusual behavior. You do not need to configure anything — anomaly detection is active for all registered agents. Secureagentics flags the following conditions:
AnomalyWhat triggers it
Unusual token countsA completion event where tokens_used is significantly higher than the agent’s historical average.
High error ratesAn agent emitting error events at a rate above its baseline within a short time window.
Policy violationsAny event blocked by an assigned policy.
Sudden traffic spikesA sharp increase in event volume relative to recent historical patterns.
When Secureagentics detects an anomaly, it:
  1. Marks the event with an anomaly flag in the Events timeline (shown as a yellow indicator).
  2. Creates an entry in the Anomalies feed under Monitoring → Anomalies.
  3. Fires any alerts you have configured for anomaly_detected (see Set Up Alerts).

​
Audit logs

Audit logs record every action taken within Secureagentics — including agent registrations, policy changes, event submissions, and blocked events. They are designed for compliance use cases where you need an immutable record of AI agent activity. Retrieve audit logs via GET /v1/audit-logs. 
import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://api.secureagentics.ai/v1"

# Retrieve the 50 most recent audit log entries
response = requests.get(
    f"{BASE_URL}/audit-logs",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"limit": 50},
)

response.raise_for_status()
logs = response.json()["logs"]
for log in logs:
    print(log["action"], log["actor"], log["created_at"])
Each audit log entry includes: 
{
  "id": "log_3x4y5z6a7b8c",
  "action": "event.blocked",
  "actor": "agent:agt_01hx9z3k2m4n5p6q7r8s9t0u",
  "resource_type": "event",
  "resource_id": "evt_09jk2l3m4n5o6p7q",
  "details": {
    "policy_id": "pol_07ab1c2d3e4f5g6h",
    "reason": "rate_limit_exceeded"
  },
  "created_at": "2026-05-04T09:42:11Z"
}
You can filter audit logs by action, actor, and time range using the same from, to, limit, and offset query parameters as the events endpoint. Export logs to your SIEM or compliance tooling by polling this endpoint on a schedule.