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)

Authentication

All endpoints require:

Authorization: Basic base64(clientId:clientSecret) header

Optional:

X-Org-ID header — Scopes results to a specific tenant

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-Org-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	No	Start of time range
`end_time`	ISO 8601	No	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):

{
  "entries": [
    {
      "id": "audit_001",
      "request_id": "req_abc123",
      "timestamp": "2025-01-02T14:30:00Z",
      "user_id": 123,
      "user_email": "[email protected]",
      "user_role": "analyst",
      "client_id": "app_456",
      "tenant_id": "my-tenant",
      "request_type": "llm_request",
      "query": "Summarize the quarterly report",
      "query_hash": "a1b2c3d4e5f6",
      "policy_decision": "allowed",
      "policy_details": {
        "evaluated": ["governance.rate_limit", "compliance.pii_check"],
        "risk_score": 0.1
      },
      "provider": "openai",
      "model": "gpt-4o",
      "response_time_ms": 1234,
      "tokens_used": 600,
      "cost": 0.012,
      "redacted_fields": [],
      "response_sample": "The quarterly report shows...",
      "compliance_flags": [],
      "security_metrics": {}
    }
  ],
  "total": 1,
  "limit": 100,
  "offset": 0
}

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-Org-ID: admin-tenant"

Path Parameters:

Parameter	Type	Description
`tenant_id`	string	Target tenant ID

Query Parameters:

Parameter	Type	Description
`limit`	integer	Max results (default: 50, max: 1000)

Response (200 OK):

{
  "entries": [
    {
      "id": "audit_001",
      "request_id": "req_abc123",
      "timestamp": "2025-01-02T14:30:00Z",
      "user_id": 123,
      "user_email": "[email protected]",
      "user_role": "analyst",
      "client_id": "app_456",
      "tenant_id": "my-tenant",
      "request_type": "llm_request",
      "query": "Summarize the quarterly report",
      "policy_decision": "allowed",
      "provider": "openai",
      "model": "gpt-4o",
      "response_time_ms": 1234,
      "tokens_used": 600,
      "cost": 0.012
    }
  ],
  "total": 50,
  "limit": 50,
  "offset": 0
}

Error Responses (POST /api/v1/audit/search):

HTTP Status	Scenario
400	`{"error": {"code": "INVALID_REQUEST", "message": "Invalid JSON in request body"}}`
400	`{"error": {"code": "INVALID_TIME_RANGE", "message": "start_time must be before end_time"}}`
401	`{"error": {"code": "UNAUTHORIZED", "message": "Missing authentication"}}`

Error Responses (GET /api/v1/audit/tenant/{tenant_id}):

HTTP Status	Scenario
401	`{"error": {"code": "UNAUTHORIZED", "message": "Missing authentication"}}`
403	`{"error": {"code": "FORBIDDEN", "message": "Access denied to tenant 'other-tenant'"}}`

Event Types

Value	Description
`llm_request`	LLM completion requests routed through the agent
`policy_evaluation`	Policy check results (block, allow, redact)
`mcp_query`	MCP connector query executions
`mcp_execute`	MCP connector tool executions
`workflow_execution`	Workflow and multi-agent plan runs
`api_call`	General API calls (CRUD operations)
`auth_event`	Authentication and authorization events
`config_change`	Configuration changes (provider, policy, connector)

Policy Decision Values

Value	Description
`allowed`	Request passed all policy checks
`blocked`	Request was blocked by a policy
`redacted`	Request was allowed but sensitive fields were redacted

Audit Entry Fields

Field	Type	Description
`id`	string	Unique audit log ID
`request_id`	string	Request correlation ID
`timestamp`	ISO 8601	When the event occurred
`user_id`	integer	User ID
`user_email`	string	User email address
`user_role`	string	User role
`client_id`	string	Client application ID
`tenant_id`	string	Tenant identifier
`request_type`	string	Type of request (freeform string)
`query`	string	User's query
`query_hash`	string	Hash of the query for deduplication
`policy_decision`	string	`allowed`, `blocked`, or `redacted`
`policy_details`	object	Details of policy evaluation
`provider`	string	LLM provider used
`model`	string	LLM model used
`response_time_ms`	integer	Request latency in milliseconds
`tokens_used`	integer	Total tokens consumed
`cost`	number	Estimated cost in USD
`redacted_fields`	array	Fields that were redacted
`error_message`	string	Error message (omitted if empty)
`response_sample`	string	Truncated response sample
`compliance_flags`	array	Compliance flags triggered
`security_metrics`	object	Security-related metrics

policy_details Object

Field	Type	Description
`evaluated`	string[]	List of policy names that were evaluated
`risk_score`	number	Calculated risk score (0.0 - 1.0)
`matched_policies`	string[]	Policies that matched and triggered actions
`evaluation_time_ms`	number	Time spent evaluating policies

security_metrics Object

Field	Type	Description
`threat_level`	string	Detected threat level: `none`, `low`, `medium`, `high`, `critical`
`patterns_matched`	integer	Number of security patterns matched
`exfiltration_risk`	boolean	Whether data exfiltration risk was detected

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 '.entries[] | select(.policy_decision == "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

Overview​

Authentication​

Endpoints​

POST /api/v1/audit/search​

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

Event Types​

Policy Decision Values​

Audit Entry Fields​

policy_details Object​

security_metrics Object​

Use Cases​

Compliance Reporting​

User Activity Analysis​

Security Incident Investigation​

Data Retention​

Error Responses​

Next Steps​