Logging, Analytics & Monitoring - Artos Documentation

Overview

System Components

Audit Logs: Complete trail of all user actions and system events
Analytics: Historical usage patterns and performance metrics
Monitoring: System health checks and real-time status
Alerting: Email notifications for critical events and thresholds
Resource Tracking: Quota usage and limits monitoring

Data Retention

All logs and analytics data are retained according to the standard data retention policy:

Hot Storage: 8 days for immediate access
Total Retention: 90 days for compliance and analysis

Audit Logs

Fetch Audit Logs

Endpoint

GET /audit/logs

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Permission Required: Admin level access Query Parameters

Parameter	Type	Required	Description
`clientId`	String	No	Filter by specific client/user ID
`startTime`	String	No	Start time (ISO 8601 format)
`endTime`	String	No	End time (ISO 8601 format)
`actionType`	String	No	Filter by action type
`category`	String	No	Filter by log category: “info”, “warning”, “error”, “security”
`page`	Integer	No	Page number (default: 1)
`limit`	Integer	No	Results per page (default: 100, max: 1000)

Supported Action Types

user_login / user_logout
document_upload / document_delete
pipeline_create / pipeline_execute / pipeline_delete
agent_create / agent_call / agent_delete
connector_create / connector_update / connector_delete
permission_denied / authentication_failed
rate_limit_exceeded / quota_exceeded
system_error / security_violation

Example Request

curl -X GET "https://api.artosai.com/audit/logs?startTime=2024-01-15T00:00:00Z&actionType=pipeline_execute&category=info" \
  -H "Authorization: Bearer admin-access-token"

Success Response (200 OK)

{
  "entries": [
    {
      "id": "log-abc123def456",
      "timestamp": "2024-01-15T10:35:22Z",
      "user_id": "user-xyz789",
      "action": "pipeline_execute",
      "category": "info",
      "resource_type": "pipeline",
      "resource_id": "pipeline-c78d9e12",
      "metadata": {
        "pipeline_name": "Clinical Trial Report Generator",
        "agent_count": 3,
        "document_count": 2,
        "execution_time_seconds": 482,
        "output_file": "phase3-efficacy-report.docx"
      },
      "ip_address": "192.168.1.100",
      "user_agent": "Mozilla/5.0...",
      "client_id": "client-app-001"
    },
    {
      "id": "log-def456ghi789",
      "timestamp": "2024-01-15T09:22:15Z",
      "user_id": "user-abc456",
      "action": "document_upload",
      "category": "info",
      "resource_type": "document",
      "resource_id": "doc-upload-789",
      "metadata": {
        "filename": "clinical-protocol.docx",
        "file_size_bytes": 2048576,
        "file_type": "docx",
        "processing_status": "completed",
        "s3_url": "s3://bucket/ingested/doc-upload-789/clinical-protocol.docx"
      },
      "ip_address": "10.0.1.50",
      "user_agent": "curl/7.68.0",
      "client_id": "api-client-002"
    },
    {
      "id": "log-ghi789jkl012",
      "timestamp": "2024-01-15T08:45:33Z",
      "user_id": "user-def789",
      "action": "authentication_failed",
      "category": "security",
      "resource_type": "auth",
      "resource_id": null,
      "metadata": {
        "failure_reason": "invalid_credentials",
        "attempted_username": "user-def789",
        "failure_count": 3,
        "account_locked": true
      },
      "ip_address": "203.0.113.42",
      "user_agent": "PostmanRuntime/7.28.0",
      "client_id": "web-app-001"
    },
    {
      "id": "log-jkl012mno345",
      "timestamp": "2024-01-15T07:12:45Z",
      "user_id": "user-ghi123",
      "action": "agent_call",
      "category": "info",
      "resource_type": "agent",
      "resource_id": "agent-search-001",
      "metadata": {
        "agent_name": "Document Search Agent",
        "execution_type": "direct_call",
        "documents_processed": 1,
        "processing_time_seconds": 12.5,
        "output_length_chars": 847,
        "connectors_used": ["conn-preset-fda-001"]
      },
      "ip_address": "172.16.0.25",
      "user_agent": "Python-requests/2.28.1",
      "client_id": "automation-script-001"
    },
    {
      "id": "log-mno345pqr678",
      "timestamp": "2024-01-15T06:33:17Z",
      "user_id": "user-jkl456",
      "action": "rate_limit_exceeded",
      "category": "warning",
      "resource_type": "api",
      "resource_id": "search_endpoint",
      "metadata": {
        "endpoint": "/retrieve",
        "rate_limit": 50,
        "requests_made": 51,
        "reset_time": "2024-01-15T07:00:00Z",
        "user_level": "regular"
      },
      "ip_address": "198.51.100.15",
      "user_agent": "MyApp/1.0",
      "client_id": "mobile-app-001"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 23,
    "total_entries": 2247,
    "entries_per_page": 100
  },
  "filters": {
    "startTime": "2024-01-15T00:00:00Z",
    "actionType": "pipeline_execute",
    "category": "info"
  }
}

Analytics

User Analytics

Endpoint

GET /analytics/user/{userId}

Path Parameters

Parameter	Type	Required	Description
`userId`	String	Yes	User ID (users can only access their own data)

Query Parameters

Parameter	Type	Required	Description
`timeRange`	String	No	Time range: “daily”, “weekly”, “monthly” (default: “weekly”)
`startDate`	String	No	Start date (YYYY-MM-DD format)
`endDate`	String	No	End date (YYYY-MM-DD format)

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Example Request

curl -X GET "https://api.artosai.com/analytics/user/user-xyz789?timeRange=monthly" \
  -H "Authorization: Bearer your-access-token"

Success Response (200 OK)

{
  "user_id": "user-xyz789",
  "time_range": "monthly",
  "period": "2024-01",
  "metrics": {
    "login_frequency": {
      "total_logins": 47,
      "unique_days": 22,
      "average_session_duration_minutes": 34.5,
      "last_login": "2024-01-15T14:30:00Z"
    },
    "document_activity": {
      "documents_uploaded": 12,
      "documents_processed": 11,
      "total_file_size_mb": 156.7,
      "processing_time_total_minutes": 127.3,
      "most_common_file_type": "docx"
    },
    "pipeline_usage": {
      "pipelines_created": 8,
      "pipelines_executed": 23,
      "total_execution_time_minutes": 645.2,
      "success_rate_percentage": 91.3,
      "most_used_agents": [
        "agent-search-001",
        "agent-mapping-002",
        "agent-custom-001"
      ]
    },
    "agent_interactions": {
      "direct_agent_calls": 15,
      "custom_agents_created": 3,
      "total_processing_time_minutes": 42.8,
      "favorite_agent_categories": ["search", "analysis"]
    },
    "api_usage": {
      "total_api_calls": 1247,
      "calls_per_day_average": 40.2,
      "most_used_endpoints": [
        "/retrieve",
        "/pipelines",
        "/documents/all"
      ],
      "error_rate_percentage": 2.1
    }
  },
  "resource_usage": {
    "current_quotas": {
      "storage_used_mb": 456.7,
      "storage_limit_mb": 5000,
      "api_calls_this_month": 1247,
      "api_calls_limit": 10000,
      "pipeline_runs_this_month": 23,
      "pipeline_runs_limit": 100,
      "documents_stored": 11,
      "documents_limit": 500
    },
    "quota_warnings": []
  }
}

System Analytics (Admin Only)

Endpoint

GET /analytics/system

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Permission Required: Admin level access Query Parameters

Parameter	Type	Required	Description
`timeRange`	String	No	Time range: “daily”, “weekly”, “monthly” (default: “weekly”)
`startDate`	String	No	Start date (YYYY-MM-DD format)
`endDate`	String	No	End date (YYYY-MM-DD format)

Example Request

curl -X GET "https://api.artosai.com/analytics/system?timeRange=weekly" \
  -H "Authorization: Bearer admin-access-token"

Success Response (200 OK)

{
  "time_range": "weekly",
  "period": "2024-01-15 to 2024-01-21",
  "system_metrics": {
    "user_activity": {
      "total_active_users": 147,
      "new_users": 8,
      "total_logins": 2341,
      "average_session_duration_minutes": 28.7
    },
    "document_processing": {
      "documents_uploaded": 432,
      "documents_processed": 398,
      "processing_success_rate": 92.1,
      "average_processing_time_minutes": 8.4,
      "total_storage_used_gb": 45.7
    },
    "pipeline_execution": {
      "pipelines_created": 89,
      "pipelines_executed": 267,
      "execution_success_rate": 89.5,
      "average_execution_time_minutes": 12.3,
      "total_processing_time_hours": 54.8
    },
    "api_performance": {
      "total_api_calls": 45672,
      "calls_per_day_average": 6524,
      "response_time_average_ms": 247,
      "error_rate_percentage": 1.8,
      "rate_limit_violations": 23
    }
  },
  "organization_quotas": {
    "storage_used_gb": 45.7,
    "storage_limit_gb": 1000,
    "api_calls_this_month": 178534,
    "api_calls_limit": 1000000,
    "pipeline_runs_this_month": 1247,
    "pipeline_runs_limit": 10000,
    "total_documents": 2847,
    "documents_limit": 50000
  }
}

Agent Analytics

Endpoint

GET /analytics/agents

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Permission Required: Admin level access Query Parameters

Parameter	Type	Required	Description
`agentId`	String	No	Filter by specific agent ID
`agentType`	String	No	Filter by agent type: “builtin” or “custom”
`timeRange`	String	No	Time range: “daily”, “weekly”, “monthly” (default: “weekly”)

Example Request

curl -X GET "https://api.artosai.com/analytics/agents?timeRange=monthly" \
  -H "Authorization: Bearer admin-access-token"

Success Response (200 OK)

{
  "time_range": "monthly",
  "period": "2024-01",
  "agent_metrics": [
    {
      "agent_id": "agent-search-001",
      "agent_name": "Document Search Agent",
      "agent_type": "builtin",
      "usage_stats": {
        "total_executions": 1247,
        "executions_in_pipelines": 987,
        "direct_calls": 260,
        "usage_frequency_per_day": 40.2,
        "unique_users": 89
      },
      "performance_stats": {
        "success_rate_percentage": 97.8,
        "average_processing_time_seconds": 8.4,
        "total_processing_time_minutes": 174.6,
        "average_output_length_chars": 847,
        "memory_usage_average_mb": 156.3
      },
      "error_analysis": {
        "total_errors": 27,
        "error_rate_percentage": 2.2,
        "most_common_errors": [
          "document_not_found",
          "processing_timeout"
        ],
        "retry_success_rate": 88.9
      }
    },
    {
      "agent_id": "agent-custom-001",
      "agent_name": "CustomAgent",
      "agent_type": "builtin",
      "usage_stats": {
        "total_executions": 456,
        "executions_in_pipelines": 389,
        "direct_calls": 67,
        "usage_frequency_per_day": 14.7,
        "unique_users": 34
      },
      "performance_stats": {
        "success_rate_percentage": 94.3,
        "average_processing_time_seconds": 15.7,
        "total_processing_time_minutes": 119.2,
        "average_output_length_chars": 1247,
        "memory_usage_average_mb": 234.7
      }
    }
  ],
  "aggregate_stats": {
    "total_agent_executions": 3456,
    "overall_success_rate": 95.7,
    "most_popular_agents": [
      "agent-search-001",
      "agent-mapping-002",
      "agent-custom-001"
    ],
    "total_processing_time_hours": 67.8
  }
}

Pipeline Analytics

Endpoint

GET /analytics/pipelines

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Permission Required: Admin level access Query Parameters

Parameter	Type	Required	Description
`pipelineId`	String	No	Filter by specific pipeline ID
`userId`	String	No	Filter by pipeline creator
`timeRange`	String	No	Time range: “daily”, “weekly”, “monthly” (default: “weekly”)

Example Request

curl -X GET "https://api.artosai.com/analytics/pipelines?timeRange=weekly" \
  -H "Authorization: Bearer admin-access-token"

Success Response (200 OK)

{
  "time_range": "weekly",
  "period": "2024-01-15 to 2024-01-21",
  "pipeline_metrics": {
    "execution_stats": {
      "total_executions": 267,
      "successful_executions": 239,
      "failed_executions": 28,
      "success_rate_percentage": 89.5,
      "executions_per_day_average": 38.1
    },
    "performance_stats": {
      "average_execution_time_minutes": 12.3,
      "fastest_execution_seconds": 47,
      "slowest_execution_minutes": 67,
      "total_processing_time_hours": 54.8,
      "agent_success_rates": {
        "agent-search-001": 98.2,
        "agent-mapping-002": 94.7,
        "agent-qc-003": 91.3
      }
    },
    "resource_usage": {
      "total_documents_processed": 1247,
      "average_documents_per_pipeline": 4.7,
      "total_output_files_generated": 239,
      "total_output_size_mb": 567.8,
      "average_output_size_mb": 2.4
    },
    "popular_configurations": [
      {
        "agent_combination": ["agent-search-001", "agent-mapping-002", "agent-qc-003"],
        "usage_count": 89,
        "success_rate": 92.1
      },
      {
        "agent_combination": ["agent-search-001", "agent-custom-001"],
        "usage_count": 67,
        "success_rate": 88.1
      }
    ]
  },
  "top_performing_pipelines": [
    {
      "pipeline_id": "pipeline-preset-001",
      "pipeline_name": "FDA Regulatory Submission",
      "execution_count": 45,
      "success_rate": 97.8,
      "average_execution_time_minutes": 8.4
    }
  ]
}

Resource Analytics

Endpoint

GET /analytics/resources

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Permission Required: Admin level access Query Parameters

Parameter	Type	Required	Description
`resourceType`	String	No	Filter by resource type: “storage”, “api”, “pipelines”, “documents”
`timeRange`	String	No	Time range: “daily”, “weekly”, “monthly” (default: “weekly”)

Example Request

curl -X GET "https://api.artosai.com/analytics/resources" \
  -H "Authorization: Bearer admin-access-token"

Success Response (200 OK)

{
  "organization_id": "org-abc123",
  "time_range": "weekly",
  "period": "2024-01-15 to 2024-01-21",
  "resource_usage": {
    "storage": {
      "total_used_gb": 45.7,
      "limit_gb": 1000,
      "usage_percentage": 4.6,
      "growth_rate_gb_per_week": 2.3,
      "projected_full_date": "2025-08-15",
      "breakdown": {
        "ingested_documents_gb": 32.4,
        "generated_documents_gb": 8.9,
        "reference_documents_gb": 2.8,
        "system_data_gb": 1.6
      }
    },
    "api_calls": {
      "total_calls_this_month": 178534,
      "limit_monthly": 1000000,
      "usage_percentage": 17.9,
      "calls_per_day_average": 5759,
      "projected_monthly_usage": 230000,
      "breakdown_by_endpoint": {
        "/retrieve": 45678,
        "/pipelines": 23456,
        "/documents/all": 18934,
        "/agents": 12456,
        "other": 78010
      }
    },
    "pipeline_runs": {
      "total_runs_this_month": 1247,
      "limit_monthly": 10000,
      "usage_percentage": 12.5,
      "runs_per_day_average": 40.2,
      "projected_monthly_usage": 1612,
      "success_rate": 89.5
    },
    "documents": {
      "total_documents": 2847,
      "limit": 50000,
      "usage_percentage": 5.7,
      "documents_per_day_average": 15.6,
      "processing_backlog": 23,
      "breakdown_by_type": {
        "docx": 1567,
        "html": 678,
        "pdf": 456,
        "csv": 146
      }
    }
  },
  "quota_warnings": [
    {
      "resource_type": "api_calls",
      "current_usage": 178534,
      "limit": 1000000,
      "threshold_percentage": 80,
      "warning_level": "none"
    }
  ]
}

Resource Quotas

Get Current Quotas

Endpoint

GET /quotas

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Query Parameters

Parameter	Type	Required	Description
`userId`	String	No	Get quotas for specific user (admin only)

Example Request

curl -X GET "https://api.artosai.com/quotas" \
  -H "Authorization: Bearer your-access-token"

Success Response (200 OK)

{
  "user_id": "user-xyz789",
  "organization_id": "org-abc123",
  "quotas": {
    "storage": {
      "used_mb": 456.7,
      "limit_mb": 5000,
      "usage_percentage": 9.1,
      "status": "normal"
    },
    "api_calls": {
      "used_this_month": 1247,
      "limit_monthly": 10000,
      "usage_percentage": 12.5,
      "reset_date": "2024-02-01T00:00:00Z",
      "status": "normal"
    },
    "pipeline_runs": {
      "used_this_month": 23,
      "limit_monthly": 100,
      "usage_percentage": 23.0,
      "reset_date": "2024-02-01T00:00:00Z",
      "status": "normal"
    },
    "documents": {
      "used": 11,
      "limit": 500,
      "usage_percentage": 2.2,
      "status": "normal"
    }
  },
  "warnings": [],
  "last_updated": "2024-01-15T15:30:00Z"
}

Organization Quotas (Admin Only)

Endpoint

GET /quotas/organization

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Permission Required: Admin level access Success Response (200 OK)

{
  "organization_id": "org-abc123",
  "quotas": {
    "storage": {
      "used_gb": 45.7,
      "limit_gb": 1000,
      "usage_percentage": 4.6,
      "status": "normal"
    },
    "api_calls": {
      "used_this_month": 178534,
      "limit_monthly": 1000000,
      "usage_percentage": 17.9,
      "reset_date": "2024-02-01T00:00:00Z",
      "status": "normal"
    },
    "pipeline_runs": {
      "used_this_month": 1247,
      "limit_monthly": 10000,
      "usage_percentage": 12.5,
      "reset_date": "2024-02-01T00:00:00Z",
      "status": "normal"
    },
    "documents": {
      "used": 2847,
      "limit": 50000,
      "usage_percentage": 5.7,
      "status": "normal"
    },
    "users": {
      "active_users": 147,
      "limit": 500,
      "usage_percentage": 29.4,
      "status": "normal"
    }
  },
  "warnings": [
    {
      "resource_type": "users",
      "threshold_percentage": 80,
      "current_percentage": 29.4,
      "status": "normal"
    }
  ],
  "last_updated": "2024-01-15T15:30:00Z"
}

System Health & Status

Health Check

Endpoint

GET /health

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Example Request

curl -X GET "https://api.artosai.com/health" \
  -H "Authorization: Bearer your-access-token"

Success Response (200 OK)

{
  "status": "healthy",
  "timestamp": "2024-01-15T15:45:00Z",
  "services": {
    "llm_deployments": {
      "anthropic": {
        "status": "up",
        "response_time_ms": 247,
        "last_check": "2024-01-15T15:44:30Z"
      },
      "openai": {
        "status": "up",
        "response_time_ms": 156,
        "last_check": "2024-01-15T15:44:30Z"
      },
      "azure_openai": {
        "status": "up",
        "response_time_ms": 198,
        "last_check": "2024-01-15T15:44:30Z"
      },
      "cohere": {
        "status": "degraded",
        "response_time_ms": 1247,
        "last_check": "2024-01-15T15:44:30Z",
        "warning": "High response time detected"
      }
    }
  },
  "overall_health": "healthy",
  "degraded_services": ["cohere"],
  "maintenance_scheduled": false
}

Degraded Response (200 OK)

{
  "status": "degraded",
  "timestamp": "2024-01-15T15:45:00Z",
  "services": {
    "llm_deployments": {
      "anthropic": {
        "status": "up",
        "response_time_ms": 247,
        "last_check": "2024-01-15T15:44:30Z"
      },
      "openai": {
        "status": "down",
        "response_time_ms": null,
        "last_check": "2024-01-15T15:44:30Z",
        "error": "Connection timeout"
      }
    }
  },
  "overall_health": "degraded",
  "failed_services": ["openai"],
  "maintenance_scheduled": false
}

Alerting System

Configure Alert Rules

Endpoint

POST /alerts/rules

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Request Body

{
  "name": "High API Usage Alert",
  "description": "Alert when API usage exceeds 80% of monthly quota",
  "rule_type": "quota_threshold",
  "conditions": {
    "resource_type": "api_calls",
    "threshold_percentage": 80,
    "evaluation_period": "hourly"
  },
  "notification": {
    "method": "email",
    "email": "[email protected]"
  },
  "enabled": true
}

Request Parameters

Field	Type	Required	Description
`name`	String	Yes	Human-readable alert rule name
`description`	String	No	Alert rule description
`rule_type`	String	Yes	Type of alert: “quota_threshold”, “latency_threshold”, “error_rate”, “system_health”
`conditions`	Object	Yes	Alert conditions and thresholds
`notification`	Object	Yes	Notification settings
`enabled`	Boolean	No	Whether alert is active (default: true)

Supported Rule Types

// Quota threshold alert
{
  "rule_type": "quota_threshold",
  "conditions": {
    "resource_type": "api_calls|storage|pipeline_runs|documents",
    "threshold_percentage": 80,
    "evaluation_period": "hourly|daily"
  }
}

// Latency threshold alert
{
  "rule_type": "latency_threshold",
  "conditions": {
    "endpoint": "/retrieve|/pipelines|all",
    "threshold_ms": 5000,
    "evaluation_period": "5min|15min|hourly"
  }
}

// Error rate alert
{
  "rule_type": "error_rate",
  "conditions": {
    "threshold_percentage": 10,
    "evaluation_period": "15min|hourly",
    "endpoint": "all|specific_endpoint"
  }
}

// System health alert
{
  "rule_type": "system_health",
  "conditions": {
    "service": "llm_deployments|all",
    "status": "down|degraded"
  }
}

Example Request

curl -X POST "https://api.artosai.com/alerts/rules" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pipeline Failure Rate Alert",
    "description": "Alert when pipeline failure rate exceeds 15%",
    "rule_type": "error_rate",
    "conditions": {
      "threshold_percentage": 15,
      "evaluation_period": "hourly",
      "endpoint": "/pipelines"
    },
    "notification": {
      "method": "email",
      "email": "[email protected]"
    },
    "enabled": true
  }'

Success Response (201 Created)

{
  "rule_id": "alert-rule-abc123",
  "name": "Pipeline Failure Rate Alert",
  "status": "created",
  "created_at": "2024-01-15T16:00:00Z",
  "next_evaluation": "2024-01-15T17:00:00Z"
}

List Alert Rules

Endpoint

GET /alerts/rules

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Query Parameters

Parameter	Type	Required	Description
`enabled`	Boolean	No	Filter by enabled status
`rule_type`	String	No	Filter by rule type

Example Request

curl -X GET "https://api.artosai.com/alerts/rules?enabled=true" \
  -H "Authorization: Bearer your-access-token"

Success Response (200 OK)

[
  {
    "rule_id": "alert-rule-abc123",
    "name": "Pipeline Failure Rate Alert",
    "description": "Alert when pipeline failure rate exceeds 15%",
    "rule_type": "error_rate",
    "conditions": {
      "threshold_percentage": 15,
      "evaluation_period": "hourly",
      "endpoint": "/pipelines"
    },
    "notification": {
      "method": "email",
      "email": "[email protected]"
    },
    "enabled": true,
    "created_at": "2024-01-15T16:00:00Z",
    "last_triggered": null,
    "trigger_count": 0
  }
]

Update Alert Rule

Endpoint

PUT /alerts/rules/{ruleId}

Path Parameters

Parameter	Type	Required	Description
`ruleId`	String	Yes	Alert rule ID

Request Body Same format as create alert rule request.

Delete Alert Rule

Endpoint

DELETE /alerts/rules/{ruleId}

Path Parameters

Parameter	Type	Required	Description
`ruleId`	String	Yes	Alert rule ID

Success Response (200 OK)

{
  "message": "Alert rule successfully deleted",
  "rule_id": "alert-rule-abc123",
  "deleted_at": "2024-01-15T17:00:00Z"
}

Scheduled Exports

Schedule Log Export

Endpoint

POST /audit/exports/schedule

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Request Body

{
  "name": "Weekly Security Logs",
  "export_type": "audit_logs",
  "format": "json",
  "filters": {
    "category": "security",
    "actionTypes": ["authentication_failed", "permission_denied", "security_violation"]
  },
  "schedule": {
    "frequency": "weekly",
    "day_of_week": "monday",
    "time": "09:00"
  },
  "delivery": {
    "method": "email",
    "email": "[email protected]",
    "subject": "Weekly Security Audit Report"
  },
  "enabled": true
}

Request Parameters

Field	Type	Required	Description
`name`	String	Yes	Human-readable export name
`export_type`	String	Yes	Type of export: “audit_logs”, “analytics”, “quotas”
`format`	String	Yes	Export format: “json” or “txt”
`filters`	Object	No	Filters to apply to the export
`schedule`	Object	Yes	Scheduling configuration
`delivery`	Object	Yes	Delivery method configuration
`enabled`	Boolean	No	Whether export is active (default: true)

Scheduling Options

// Daily export
{
  "frequency": "daily",
  "time": "09:00"
}

// Weekly export
{
  "frequency": "weekly",
  "day_of_week": "monday|tuesday|wednesday|thursday|friday|saturday|sunday",
  "time": "09:00"
}

// Monthly export
{
  "frequency": "monthly",
  "day_of_month": 1,
  "time": "09:00"
}

// Custom schedule (cron format)
{
  "frequency": "custom",
  "cron_expression": "0 9 * * 1"
}

Example Request

curl -X POST "https://api.artosai.com/audit/exports/schedule" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly Analytics Report",
    "export_type": "analytics",
    "format": "json",
    "schedule": {
      "frequency": "monthly",
      "day_of_month": 1,
      "time": "08:00"
    },
    "delivery": {
      "method": "email",
      "email": "[email protected]",
      "subject": "Monthly Platform Analytics Report"
    },
    "enabled": true
  }'

Success Response (201 Created)

{
  "export_id": "export-schedule-abc123",
  "name": "Monthly Analytics Report",
  "status": "scheduled",
  "created_at": "2024-01-15T16:30:00Z",
  "next_execution": "2024-02-01T08:00:00Z"
}

List Scheduled Exports

Endpoint

GET /audit/exports/schedule

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Success Response (200 OK)

[
  {
    "export_id": "export-schedule-abc123",
    "name": "Monthly Analytics Report",
    "export_type": "analytics",
    "format": "json",
    "schedule": {
      "frequency": "monthly",
      "day_of_month": 1,
      "time": "08:00"
    },
    "delivery": {
      "method": "email",
      "email": "[email protected]"
    },
    "enabled": true,
    "created_at": "2024-01-15T16:30:00Z",
    "last_execution": null,
    "next_execution": "2024-02-01T08:00:00Z",
    "execution_count": 0
  }
]

Update Scheduled Export

Endpoint

PUT /audit/exports/schedule/{exportId}

Path Parameters

Parameter	Type	Required	Description
`exportId`	String	Yes	Export schedule ID

Request Body Same format as create scheduled export request.

Delete Scheduled Export

Endpoint

DELETE /audit/exports/schedule/{exportId}

Path Parameters

Parameter	Type	Required	Description
`exportId`	String	Yes	Export schedule ID

Success Response (200 OK)

{
  "message": "Scheduled export successfully deleted",
  "export_id": "export-schedule-abc123",
  "deleted_at": "2024-01-15T17:30:00Z"
}

Error Handling

Common Error Codes

Error Code	HTTP Status	Description
`INSUFFICIENT_PERMISSIONS`	403	User lacks permission to access logs/analytics
`INVALID_TIME_RANGE`	400	Invalid date format or time range
`RESOURCE_NOT_FOUND`	404	Requested resource (user, pipeline, etc.) not found
`ALERT_RULE_LIMIT_EXCEEDED`	400	Too many alert rules configured
`INVALID_ALERT_CONDITIONS`	400	Alert conditions are malformed
`EXPORT_SCHEDULE_CONFLICT`	409	Scheduled export with same name already exists
`QUOTA_EXCEEDED`	429	Export or analytics request limit reached

Error Response Format

{
  "error_code": "INSUFFICIENT_PERMISSIONS",
  "message": "User does not have permission to access system-wide analytics",
  "details": {
    "required_permission": "admin",
    "user_permission": "user",
    "resource_type": "system_analytics"
  },
  "request_id": "req-abc123def456"
}

Best Practices

Efficient Log Analysis

# Example: Analyzing audit logs for security patterns
import requests
from datetime import datetime, timedelta

class SecurityAnalyzer:
    def __init__(self, base_url, admin_token):
        self.base_url = base_url
        self.headers = {
            'Authorization': f'Bearer {admin_token}',
            'Content-Type': 'application/json'
        }
    
    def analyze_security_events(self, days_back=7):
        """Analyze security events from the last N days"""
        end_time = datetime.now()
        start_time = end_time - timedelta(days=days_back)
        
        # Fetch security logs
        response = requests.get(
            f"{self.base_url}/audit/logs",
            headers=self.headers,
            params={
                'category': 'security',
                'startTime': start_time.isoformat(),
                'endTime': end_time.isoformat(),
                'limit': 1000
            }
        )
        
        logs = response.json()['entries']
        
        # Analyze patterns
        failed_logins = [log for log in logs if log['action'] == 'authentication_failed']
        permission_denials = [log for log in logs if log['action'] == 'permission_denied']
        
        # Generate summary
        return {
            'total_security_events': len(logs),
            'failed_login_attempts': len(failed_logins),
            'permission_denials': len(permission_denials),
            'suspicious_ips': self._identify_suspicious_ips(failed_logins),
            'affected_users': list(set([log['user_id'] for log in logs]))
        }
    
    def _identify_suspicious_ips(self, failed_logins):
        """Identify IPs with multiple failed login attempts"""
        ip_counts = {}
        for log in failed_logins:
            ip = log['ip_address']
            ip_counts[ip] = ip_counts.get(ip, 0) + 1
        
        return [ip for ip, count in ip_counts.items() if count >= 5]

# Usage
analyzer = SecurityAnalyzer("https://api.artosai.com", "admin-token")
security_report = analyzer.analyze_security_events(days_back=7)
print(f"Security events analyzed: {security_report}")

Monitoring Dashboard Integration

// Example: Building a monitoring dashboard
class MonitoringDashboard {
    constructor(apiClient) {
        this.api = apiClient;
        this.refreshInterval = 60000; // 1 minute
    }
    
    async initializeDashboard() {
        // Get current system health
        const health = await this.api.getSystemHealth();
        this.updateHealthStatus(health);
        
        // Get resource usage
        const resources = await this.api.getResourceAnalytics();
        this.updateResourceMetrics(resources);
        
        // Get recent activity
        const userAnalytics = await this.api.getUserAnalytics();
        this.updateActivityMetrics(userAnalytics);
        
        // Set up automatic refresh
        this.startAutoRefresh();
    }
    
    async checkAlerts() {
        try {
            const resources = await this.api.getResourceAnalytics();
            const warnings = [];
            
            // Check quota thresholds
            Object.entries(resources.organization_quotas).forEach(([resource, data]) => {
                if (data.usage_percentage > 80) {
                    warnings.push({
                        type: 'quota_warning',
                        resource: resource,
                        usage: data.usage_percentage,
                        message: `${resource} usage at ${data.usage_percentage}%`
                    });
                }
            });
            
            // Display warnings
            if (warnings.length > 0) {
                this.displayWarnings(warnings);
            }
            
        } catch (error) {
            console.error('Alert check failed:', error);
        }
    }
    
    startAutoRefresh() {
        setInterval(async () => {
            await this.checkAlerts();
            const health = await this.api.getSystemHealth();
            this.updateHealthStatus(health);
        }, this.refreshInterval);
    }
}

Performance Monitoring

Set up proactive alerts for critical thresholds
Monitor quota usage to prevent service interruptions
Track error rates to identify system issues early
Analyze usage patterns to optimize resource allocation
Regular security reviews of audit logs

Alert Configuration Strategy

// Recommended alert rules for production environments
[
  {
    "name": "Critical API Error Rate",
    "rule_type": "error_rate",
    "conditions": {
      "threshold_percentage": 5,
      "evaluation_period": "15min",
      "endpoint": "all"
    },
    "notification": {
      "method": "email",
      "email": "[email protected]"
    }
  },
  {
    "name": "Storage Usage Warning",
    "rule_type": "quota_threshold",
    "conditions": {
      "resource_type": "storage",
      "threshold_percentage": 85,
      "evaluation_period": "daily"
    }
  },
  {
    "name": "LLM Service Degradation",
    "rule_type": "system_health",
    "conditions": {
      "service": "llm_deployments",
      "status": "degraded"
    }
  }
]

Integration Notes

Upcoming Features

Slack Integration: Alert delivery via Slack channels (coming soon)
Microsoft Teams Integration: Alert delivery via Teams channels (coming soon)
Real-time Monitoring: WebSocket-based real-time event streaming (planned)
External Tool Integration: Prometheus metrics and Grafana dashboards (planned)

Current Limitations

Email is the only supported alert delivery method
Historical data only (no real-time streaming)
Log exports limited to JSON and TXT formats
No external monitoring tool integrations yet

API Documentation

Concepts

SDK Reference

Integrations

Deployment

​Overview

​System Components

​Data Retention

​Audit Logs

​Fetch Audit Logs

​Analytics

​User Analytics

​System Analytics (Admin Only)

​Agent Analytics

​Pipeline Analytics

​Resource Analytics

​Resource Quotas

​Get Current Quotas

​Organization Quotas (Admin Only)

​System Health & Status

​Health Check

​Alerting System

​Configure Alert Rules

​List Alert Rules

​Update Alert Rule

​Delete Alert Rule

​Scheduled Exports

​Schedule Log Export

​List Scheduled Exports

​Update Scheduled Export

​Delete Scheduled Export

​Error Handling

​Common Error Codes

​Error Response Format

​Best Practices

​Efficient Log Analysis

​Monitoring Dashboard Integration

​Performance Monitoring

​Alert Configuration Strategy

​Integration Notes

​Upcoming Features

​Current Limitations

Overview

System Components

Data Retention

Audit Logs

Fetch Audit Logs

Analytics

User Analytics

System Analytics (Admin Only)

Agent Analytics

Pipeline Analytics

Resource Analytics

Resource Quotas

Get Current Quotas

Organization Quotas (Admin Only)

System Health & Status

Health Check

Alerting System

Configure Alert Rules

List Alert Rules

Update Alert Rule

Delete Alert Rule

Scheduled Exports

Schedule Log Export

List Scheduled Exports

Update Scheduled Export

Delete Scheduled Export

Error Handling

Common Error Codes

Error Response Format

Best Practices

Efficient Log Analysis

Monitoring Dashboard Integration

Performance Monitoring

Alert Configuration Strategy

Integration Notes

Upcoming Features

Current Limitations