Fastio API Audit Log Retrieval: A Developer's Tutorial

Audit log retrieval via the Fastio API lets developers export and monitor agent and human interactions for security and compliance. When AI agents and humans share a workspace, tracking every file read, write, and permission change is a hard security requirement.

Automating this export removes the manual work of downloading CSVs from a dashboard. Direct log ingestion speeds up compliance reporting, so security teams can analyze anomalies instead of just gathering data. Fastio offers a dedicated REST API endpoint for pulling these event streams into your SIEM systems.

This guide covers the technical details for authenticating, querying the log endpoint, and handling the JSON payloads. We will build an export script that handles rate limits and pagination. By the end, you will have a working pipeline to extract agent activity.

Before making requests to the Fastio audit logs API, you need a valid API key with the correct permissions. Fastio uses standard Bearer token authentication for all API endpoints.

To generate your key, navigate to your workspace settings, select "Developer Settings," and create a new API token. Ensure you assign the audit_logs:read scope to this token. Without this specific scope, the API returns a multiple Forbidden response.

Here is how you structure the authorization header in your requests:

curl -X GET "https://api.fast.io/v1/workspaces/{workspace_id}/audit-logs" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Keep your tokens secure. Never hardcode them in your application code. Use environment variables or a secrets manager, especially in production. If you are integrating this into an AI agent's workflow, consider using the built-in 251 MCP tools available via our Storage for Agents integration, which handles context and authentication securely. The MCP integration allows agents to self-audit their own workspaces if granted the appropriate permissions.

The core endpoint for fetching compliance logs is the workspace audit logs route. It returns a structured JSON array containing every event in the specified workspace.

A basic GET request returns the 100 most recent events. Each event object includes a timestamp, the actor (human or AI agent), the action performed, and the target resource.

{
  "events": [
    {
      "id": "evt_987654321",
      "timestamp": "2026-02-24T14:32:01Z",
      "actor": {
        "type": "agent",
        "id": "agt_12345",
        "name": "DataProcessorBot"
      },
      "action": "file.download",
      "resource": {
        "type": "file",
        "id": "file_abc123",
        "path": "/reports/q1_financials.pdf"
      },
      "ip_address": "192.168.1.50"
    }
  ],
  "has_more": true,
  "next_cursor": "cXF3ZXIxMjM="
}

This JSON structure makes parsing the data simple. Notice the actor.type field. It distinguishes between human users and AI agents, helping you monitor autonomous system behavior in shared workspaces. You can track exactly which files an OpenClaw agent accessed during its task. For more details on OpenClaw, check the Storage for OpenClaw guide.

Workspace audit logs grow quickly, especially when multiple AI agents process files at once. The Fastio API uses cursor-based pagination to deliver large datasets without timing out.

When the API response includes "has_more": true, additional events exist. Extract the next_cursor value and pass it in your next request using the cursor query parameter. Storing the final cursor from your last successful run lets you resume extraction later without pulling duplicate data.

Here is a Python example showing how to paginate through all available logs while storing the state:

import requests
import time
import json

def fetch_all_audit_logs(workspace_id, api_token, last_cursor=None):
    base_url = f"https://api.fast.io/v1/workspaces/{workspace_id}/audit-logs"
    headers = {"Authorization": f"Bearer {api_token}"}
    logs = []
    cursor = last_cursor
    
    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor
            
        response = requests.get(base_url, headers=headers, params=params)
        
        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 5))
            print(f"Rate limited. Waiting {retry_after} seconds.")
            time.sleep(retry_after)
            continue
            
        response.raise_for_status()
        data = response.json()
        
        logs.extend(data.get("events", []))
        
        if not data.get("has_more"):
            break
            
        cursor = data.get("next_cursor")
        time.sleep(0.5) # Basic rate limit spacing
        
    # Save the final cursor for the next job run
    with open("last_cursor.txt", "w") as f:
        f.write(cursor if cursor else "")
        
    return logs

This script includes basic rate limit handling. Fastio enforces API rate limits to maintain stability. If you exceed the limit, the API returns a multiple Too Many Requests status. Your code must intercept this and respect the Retry-After header before continuing. Handling this prevents your daily compliance cron jobs from failing.

Secure Your AI Agent Workflows

Get 50GB of free storage, full API access, and 251 MCP tools to build and monitor your agentic applications.

Sign Up Free

Pulling the entire workspace history is rarely needed for daily monitoring. You usually want to isolate specific behaviors, like tracking when a new AI agent modifies files or finding failed logins.

The Fastio compliance logging API supports server-side filtering via query parameters. This reduces payload size and speeds up your script.

Available filter parameters include:

• start_date and end_date: ISO multiple formatted timestamps to bound the query.
• actor_type: Filter by human or agent.
• action: Restrict results to specific event types like file.delete, workspace.invite, or role.update.

To find all file deletions performed by AI agents in the last 24 hours, you would construct your request like this:

curl -X GET "https://api.fast.io/v1/workspaces/{id}/audit-logs?actor_type=agent&action=file.delete&start_date=2026-02-23T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Filtering at the API level is much more efficient than downloading everything and filtering locally. It minimizes bandwidth and prevents memory exhaustion in your scripts. For strict compliance frameworks, filtering lets you retain only the events your auditors require.

After retrieving the JSON payload from the API, the next step is routing that data into your security infrastructure. Most teams push these logs into platforms like Splunk, Datadog, or Elasticsearch for long-term storage and alerting.

Because the Fastio API outputs standard JSON, transformation is minimal. You will just need to normalize the data to match your SIEM's schema. For example, map Fastio's timestamp field to @timestamp for Elasticsearch, or wrap the event payload in the format Splunk's HTTP Event Collector (HEC) expects.

For a continuous ingestion pipeline, consider webhooks instead of polling the REST API. Fastio supports webhooks for workspace events, so your system receives POST requests immediately when an action occurs. This reactive pattern works well for real-time alerting on sensitive actions, like an ownership transfer or an unexpected bulk download.

If you are building an automated setup, check the Fastio API Documentation for the complete list of webhook event payloads. Combining webhooks with API polling ensures you capture real-time alerts while keeping a verifiable historical record.

Developers can test the audit log extraction process using the Fastio free agent tier. This tier provides 50GB of free storage, a 1GB maximum file size, and 5,000 monthly credits with no credit card required.

Spin up a test workspace, connect a local agent using the MCP server, generate some file activity, and use the API to extract the logs. Your security team can use this to validate the SIEM ingestion pipeline before rolling Fastio out across the organization.

Since agents and humans share the exact same workspaces, the auditing setup you build for the free tier translates directly to production. Every file uploaded during testing is automatically indexed and available for intelligence queries, and every query appears in the audit stream. Read more about configuring these shared environments in our Storage for Agents overview.