Audit Search API

Search and retrieve audit logs for compliance, debugging, and analytics through the Orchestrator API.

Overview

The Audit API provides:

• Search Capabilities: Filter logs by user, client, time range, and request type
• Tenant Isolation: Access audit logs scoped to specific tenants
• Compliance Support: Full audit trail for regulatory requirements

Base URL: http://localhost:8081 (Orchestrator)

---

Endpoints

POST /api/v1/audit/search

Search audit logs with flexible filtering criteria.

Request:

curl -X POST http://localhost:8081/api/v1/audit/search \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: my-tenant" \
  -d '{
    "user_email": "[email protected]",
    "start_time": "2025-01-01T00:00:00Z",
    "end_time": "2025-01-02T23:59:59Z",
    "request_type": "llm_request",
    "limit": 100
  }'

Request Body:

Field	Type	Required	Description
user_email	string	No	Filter by user email
client_id	string	No	Filter by client/application ID
start_time	ISO 8601	Yes	Start of time range
end_time	ISO 8601	Yes	End of time range
request_type	string	No	Filter by request type
limit	integer	No	Max results (default: 100, max: 1000)

Request Types:

Type	Description
llm_request	LLM completion requests
policy_evaluation	Policy check results
mcp_query	MCP connector queries
workflow_execution	Workflow runs
api_call	General API calls

Response (200 OK):

{
  "logs": [
    {
      "id": "audit_001",
      "timestamp": "2025-01-02T14:30:00Z",
      "tenant_id": "my-tenant",
      "user": {
        "id": "user_123",
        "email": "[email protected]"
      },
      "client_id": "app_456",
      "request_type": "llm_request",
      "request": {
        "query": "Summarize the quarterly report",
        "model": "gpt-4o",
        "provider": "openai"
      },
      "response": {
        "status": "success",
        "latency_ms": 1234,
        "tokens": {
          "prompt": 150,
          "completion": 450,
          "total": 600
        }
      },
      "policies_evaluated": ["governance.rate_limit", "compliance.pii_check"],
      "policies_triggered": [],
      "metadata": {
        "ip_address": "192.168.1.1",
        "user_agent": "AxonFlow-SDK/1.0"
      }
    }
  ],
  "total": 1,
  "has_more": false
}

---

GET /api/v1/audit/tenant/{tenant_id}

Get recent audit logs for a specific tenant. Useful for admin dashboards.

Request:

curl http://localhost:8081/api/v1/audit/tenant/my-tenant \
  -H "X-Tenant-ID: admin-tenant"

Path Parameters:

Parameter	Type	Description
tenant_id	string	Target tenant ID

Response (200 OK):

{
  "tenant_id": "my-tenant",
  "logs": [
    {
      "id": "audit_001",
      "timestamp": "2025-01-02T14:30:00Z",
      "user": {
        "id": "user_123",
        "email": "[email protected]"
      },
      "request_type": "llm_request",
      "request": {
        "query": "Summarize the quarterly report",
        "model": "gpt-4o"
      },
      "response": {
        "status": "success",
        "latency_ms": 1234
      }
    }
  ],
  "count": 50,
  "limit": 50
}

---

Audit Log Structure

Core Fields

Field	Type	Description
id	string	Unique audit log ID
timestamp	ISO 8601	When the event occurred
tenant_id	string	Tenant identifier
user	object	User who initiated the request
client_id	string	Client application ID
request_type	string	Type of request

Request Object

Field	Type	Description
query	string	User's query (may be truncated)
model	string	LLM model used
provider	string	LLM provider
connector	string	MCP connector (if applicable)

Response Object

Field	Type	Description
status	string	success, error, blocked
latency_ms	integer	Request latency in milliseconds
tokens	object	Token usage (prompt, completion, total)
error	string	Error message (if status is error)
blocked_by	string	Policy that blocked (if status is blocked)

Policy Fields

Field	Type	Description
policies_evaluated	array	Policies that were checked
policies_triggered	array	Policies that matched/blocked

---

Use Cases

Compliance Reporting

Generate audit reports for specific time periods:

curl -X POST http://localhost:8081/api/v1/audit/search \
  -H "Content-Type: application/json" \
  -d '{
    "start_time": "2025-01-01T00:00:00Z",
    "end_time": "2025-01-31T23:59:59Z",
    "request_type": "policy_evaluation",
    "limit": 1000
  }'

User Activity Analysis

Track specific user's activity:

curl -X POST http://localhost:8081/api/v1/audit/search \
  -H "Content-Type: application/json" \
  -d '{
    "user_email": "[email protected]",
    "start_time": "2025-01-02T00:00:00Z",
    "end_time": "2025-01-02T23:59:59Z",
    "limit": 500
  }'

Security Incident Investigation

Find blocked requests:

curl -X POST http://localhost:8081/api/v1/audit/search \
  -H "Content-Type: application/json" \
  -d '{
    "start_time": "2025-01-02T00:00:00Z",
    "end_time": "2025-01-02T23:59:59Z",
    "limit": 100
  }' | jq '.logs[] | select(.response.status == "blocked")'

---

Data Retention

Tier	Retention Period
Community	7 days
Professional	30 days
Enterprise	365 days

note

For compliance requirements (RBI, SEBI, EU AI Act), see the enterprise compliance modules for extended retention and regulatory exports.

---

Error Responses

HTTP Status	Error Code	Description
400	INVALID_REQUEST	Invalid request body or parameters
400	INVALID_TIME_RANGE	Invalid time range specified
401	UNAUTHORIZED	Missing authentication
403	FORBIDDEN	Access denied to tenant
500	INTERNAL_ERROR	Audit search failed

---

Next Steps

• Agent Endpoints - Policy enforcement API
• Governance - Audit Logging - Audit logging guide
• SDK Documentation - Language-specific SDKs