> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duvo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Audit Log and Activity Tracking
> What Duvo records about agent activity, where to find it in the product, how to export it via the API for your SIEM, and the known gaps to plan compensating controls around.
Security and compliance teams can use this guide to answer: **what did Duvo do, on whose behalf, and when?** It covers what Duvo records, where to find that data in the product, how to export it for your SIEM or compliance tooling, and what is not yet captured so you can plan compensating controls.
## What Gets Recorded
Duvo records activity in four event families.
### Actor events
Changes to who can access Duvo and how they authenticate:
| Event | What is captured |
| ------------------------------------ | ----------------------------------------------------------- |
| User login | User, timestamp, identity provider |
| User invited to team or organization | Inviting user, invitee, role assigned, timestamp |
| Role changed | Acting user, target user, old role, new role, timestamp |
| Connection added or removed | User, connection type, team, timestamp |
| Login or secret created or rotated | User, secret name (never the value), agent scope, timestamp |
| API key created or revoked | Creating user, key name, timestamp |
### Builder events
Changes to automation configuration:
| Event | What is captured |
| ---------------------------- | ---------------------------------------- |
| Agent created | User, agent name, team, timestamp |
| AOP edited | User, agent, version number, timestamp |
| Agent published | User, agent, version promoted, timestamp |
| Schedule enabled or disabled | User, agent, interval, timestamp |
| Trigger added or removed | User, agent, trigger type, timestamp |
| Agent duplicated | User, source agent, new agent, timestamp |
| Agent deleted | User, agent, timestamp |
### Run events
Activity during each Run execution:
| Event | What is captured |
| --------------------------------- | ---------------------------------------------- |
| Run started | User or trigger type, agent, run ID, timestamp |
| Tool call made | Tool name, connection, run ID, timestamp |
| Human-in-the-Loop request created | Assignee, run ID, request title, timestamp |
| HITL request approved or rejected | Reviewer, decision, run ID, timestamp |
| Run completed | Run ID, status, duration, timestamp |
| Run stopped manually | User, run ID, timestamp |
### Admin events
Organizational-level changes:
| Event | What is captured |
| -------------------------------------- | --------------------------------------------- |
| Team created | User, team name, organization, timestamp |
| User removed from team or organization | Acting admin, removed user, timestamp |
| Owner or Admin role assigned | Acting user, target user, new role, timestamp |
| Billing plan changed | Admin, old plan, new plan, timestamp |
## Finding Audit Data in the Product
### Runs List
**Past Runs** (left sidebar) is the primary place to review run-level activity. Every Run across all agents appears here with its status, trigger source, creating user, and timestamps.
Admins and Managers see the **Created by** column, which shows which team member started each Run. Use the filter bar to narrow by:
* **Agent** — activity for a specific automation
* **Status** — Failed, Completed, Running, or Stopped runs
* **Created by** — activity from a specific team member (Admin and Manager only)
* **Trigger** — runs started manually, by schedule, by API, or by event trigger
### Team Insights
**Team Insights** (sidebar, under Team) shows aggregated activity: run counts, completion rates, active agents, and usage trends over time. Use this to spot sudden drops in activity or failure rate spikes across the whole team.
### Human-in-the-Loop activity
All HITL approval requests, responses, and outcomes are recorded as part of the Run's message thread. Open any Run that included a HITL step to see who approved or rejected the request, when, and with what context.
## Exporting Audit Data
### From the Runs List
To export run-level activity:
Open **Past Runs** from the sidebar.
Apply filters (agent, date range, status, created by).
Click **Export** in the top-right corner.
Choose **CSV** or **JSON**.
Each export row contains: agent name, run ID, status, trigger type, created-by user, start time, end time, and duration. The run ID can then be used to retrieve the full message log via the API (see below).
Download sample exports to inspect the exact field names and format:
* [past-runs-sample.csv](/images/user-guide/security/past-runs-sample.csv)
* [past-runs-sample.json](/images/user-guide/security/past-runs-sample.json)
### Via the Public API
Use the API to retrieve run history and build a custom audit export pipeline.
**List recent runs for your team:**
```bash theme={"dark"}
curl -X GET "https://api.duvo.ai/v2/teams/{teamId}/runs?limit=100&sort_by=created_at&sort_order=desc" \
-H "Authorization: Bearer dv_your_api_key"
```
Filter parameters:
| Parameter | Description |
| ---------- | --------------------------------------------------------------- |
| `limit` | Number of runs per page (1–100, default 20) |
| `offset` | Number of runs to skip for pagination |
| `agent_id` | Scope to a specific agent |
| `status` | Filter by run status (completed, failed, running, stopped) |
| `source` | Filter by how the run was started (api, schedule, manual, etc.) |
**Get status for a specific Run:**
```bash theme={"dark"}
curl -X GET "https://api.duvo.ai/v2/runs/{run_id}" \
-H "Authorization: Bearer dv_your_api_key"
```
**Get the full execution log for one Run:**
```bash theme={"dark"}
curl -X GET "https://api.duvo.ai/v2/runs/{run_id}/messages?limit=100" \
-H "Authorization: Bearer dv_your_api_key"
```
The messages endpoint returns every step the agent took — tool calls, model responses, HITL requests, and final output — in chronological order.
## Integrating with a SIEM or Observability Tool
Duvo does not currently have a native push connector for SIEM tools (Splunk, Datadog, Elasticsearch, etc.). The supported approach is a pull-based pipeline using the public API.
### Building a polling pipeline
Schedule a polling script (a cron job, Lambda, or Cloud Run job) that calls `GET /teams/{teamId}/runs` with `sort_order=asc` and an `offset` cursor to page through new Runs since your last poll.
For each Run, call `GET /runs/{run_id}/messages` to get the full execution log.
Transform and forward the results to your SIEM using its HTTP ingestion endpoint — for example, Splunk HTTP Event Collector (HEC) or the Datadog Logs API.
`GET /runs/{run_id}` returns a JSON object like this:
```json theme={"dark"}
{
"run_id": "550e8400-e29b-41d4-a716-446655440000",
"assignment_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"assignment_name": "Invoice Processing",
"status": "completed",
"trigger": "schedule",
"created_by": "user@example.com",
"started_at": "2026-05-18T09:00:00.000Z",
"completed_at": "2026-05-18T09:03:42.000Z",
"duration_seconds": 222
}
```
For the full API reference, see [Running Agents via API](/user-guide/running-assignments/running-assignments-via-api).
## Retention and Access Control
### Who can view audit data
| Role | Run history | Created by column | Run Debugger | Team Insights | API access |
| ------- | ------------- | ----------------- | ------------ | ------------- | ------------- |
| Member | Own runs only | No | No | No | Own runs only |
| Manager | All team runs | Yes | No | Yes | All team runs |
| Admin | All team runs | Yes | Yes | Yes | All team runs |
| Owner | All team runs | Yes | Yes | Yes | All team runs |
Organization Admins, Owners, and Executives have access to every team's data within the organization.
For a full breakdown of role capabilities, see [Team Roles and Permissions](/user-guide/teams/roles-and-permissions) and [Organization Roles and Permissions](/user-guide/organizations/roles-and-permissions).
### Data retention
Run history and audit data is retained for the duration of your subscription. Contact [security@duvo.ai](mailto:security@duvo.ai) if you need a full data export or have questions about retention windows under your plan.
## Known Gaps
Be aware of these limitations when planning compensating controls.
| What you may expect | Current state | Workaround |
| ---------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------- |
| Native SIEM push (Splunk HEC, Datadog) | Not available — pull only | Schedule a polling script that forwards runs to your SIEM (see above) |
| Dedicated audit log API endpoint | Not available — use the runs API | Use `GET /teams/{teamId}/runs` with message logs for per-run detail |
| Actor and builder event export | In-product only — not yet exportable via API | Contact [security@duvo.ai](mailto:security@duvo.ai) for a data extract |
| Per-step tool timing | Not exposed via the API | Overall Run duration is available via `GET /runs/{run_id}` |
| Per-step cost breakdown | Not exposed via the API | Use Team Insights for aggregated cost trends |
| OpenTelemetry trace IDs in API responses | Not currently exposed | Use `run_id` as the stable correlation key in your SIEM |
| Signed or tamper-evident log export | Not currently supported | Supplement with your SIEM's ingestion integrity controls |
## Related
Risk tiers, HITL patterns, and kill switches for sensitive agents
Filtering and monitoring all Runs across your team
API reference for starting runs, polling status, and retrieving messages
Team-level roles and what each can see
Org-level access and which roles have cross-team visibility
Platform-level security controls, SOC 2, and data handling