Analytics Endpoints

The analytics endpoints provide comprehensive management of analytics
assets, data sources, and analytical processing capabilities. These
endpoints allow providers to create, configure, and manage their
analytics offerings while enabling consumers to execute and interact
with purchased analytics.

Analytics Asset Management

List Analytics Assets

Retrieve all analytics assets for your company.

GET /analytics/assets

List Analytics Assets Query Parameters

status (optional): Filter by asset status (draft, published,
archived)
category (optional): Filter by analytics category
data_source (optional): Filter by connected data source
sort (optional): Sort order (created_at, updated_at, name)
limit (optional): Results per page (default: 50)
offset (optional): Pagination offset (default: 0)

List Analytics Assets Response

{
  "data": [
    {
      "asset_id": "asset_123",
      "name": "Customer Churn Predictor",
      "description": "ML model predicting customer churn probability",
      "status": "published",
      "category": "machine_learning",
      "data_sources": ["bigquery_production", "snowflake_analytics"],
      "created_at": "2024-08-15T10:00:00Z",
      "updated_at": "2025-01-15T14:30:00Z",
      "version": "2.1.0",
      "performance_metrics": {
        "accuracy": 0.92,
        "avg_response_time": 180,
        "requests_last_30d": 15000
      },
      "revenue_metrics": {
        "monthly_revenue": 4500.00,
        "total_customers": 67
      }
    }
  ],
  "meta": {
    "total": 12,
    "published": 8,
    "draft": 3,
    "archived": 1
  }
}

Create Analytics Asset

Create a new analytics asset from data sources.

POST /analytics/assets

Create Analytics Asset Request Body

{
  "name": "Revenue Forecasting Model",
  "description": "Advanced time-series forecasting for revenue prediction",
  "category": "forecasting",
  "data_sources": [
    {
      "source_id": "bigquery_sales",
      "tables": ["sales_transactions", "customer_data"],
      "access_level": "read_only"
    }
  ],
  "configuration": {
    "model_type": "time_series",
    "algorithms": ["arima", "prophet", "lstm"],
    "features": [
      "historical_revenue",
      "seasonality_indicators",
      "external_factors"
    ],
    "output_format": "json",
    "batch_processing": true
  },
  "validation_rules": {
    "min_data_points": 100,
    "required_columns": ["date", "revenue", "product_category"],
    "date_range_validation": true
  },
  "pricing": {
    "model": "per_request",
    "price": 5.00,
    "currency": "USD",
    "free_tier": {
      "requests": 50,
      "period": "monthly"
    }
  }
}

Create Analytics Asset Response

{
  "data": {
    "asset_id": "asset_456",
    "name": "Revenue Forecasting Model",
    "status": "draft",
    "version": "1.0.0",
    "created_at": "2025-01-20T16:30:00Z",
    "data_sources": [
      {
        "source_id": "bigquery_sales",
        "connection_status": "connected",
        "last_validated": "2025-01-20T16:30:00Z"
      }
    ],
    "endpoint": {
      "url": "https://api.spartera.com/analytics/asset_456/execute",
      "methods": ["POST"],
      "authentication": "required"
    },
    "next_steps": [
      "Configure model parameters",
      "Run validation tests",
      "Publish to marketplace"
    ]
  }
}

Get Analytics Asset Details

Retrieve detailed information about a specific analytics asset.

GET /analytics/assets/{asset_id}

Get Analytics Asset Details Parameters

asset_id (path, required): Analytics asset identifier

Get Analytics Asset Details Response

{
  "data": {
    "asset_id": "asset_123",
    "name": "Customer Churn Predictor",
    "description": "Machine learning model that predicts the probability of customer churn using behavioral patterns, transaction history, and engagement metrics.",
    "status": "published",
    "category": "machine_learning",
    "subcategory": "classification",
    "version": "2.1.0",
    "created_at": "2024-08-15T10:00:00Z",
    "updated_at": "2025-01-15T14:30:00Z",
    "data_sources": [
      {
        "source_id": "bigquery_production",
        "name": "Production Database",
        "type": "bigquery",
        "tables": ["customers", "transactions", "engagement_events"],
        "connection_status": "active",
        "last_sync": "2025-01-20T15:00:00Z"
      }
    ],
    "configuration": {
      "model_type": "gradient_boosting",
      "algorithms": ["xgboost", "random_forest"],
      "features": [
        "transaction_frequency",
        "engagement_score",
        "support_tickets",
        "payment_history"
      ],
      "target_variable": "churned_90_days",
      "validation_split": 0.2,
      "performance_threshold": 0.85
    },
    "api_specification": {
      "endpoint": "https://api.spartera.com/analytics/asset_123/predict",
      "methods": ["POST"],
      "input_schema": {
        "customer_id": "string",
        "include_features": "boolean",
        "prediction_horizon": "integer"
      },
      "output_schema": {
        "customer_id": "string",
        "churn_probability": "float",
        "risk_level": "string",
        "key_factors": "array"
      }
    },
    "performance_metrics": {
      "accuracy": 0.92,
      "precision": 0.89,
      "recall": 0.94,
      "f1_score": 0.91,
      "auc_roc": 0.96,
      "avg_response_time": 180,
      "uptime_percentage": 99.7
    },
    "usage_statistics": {
      "total_requests": 125000,
      "requests_last_30d": 15000,
      "unique_customers": 67,
      "avg_requests_per_customer": 223
    },
    "marketplace_info": {
      "published": true,
      "marketplace_id": "analytics_123",
      "rating": 4.6,
      "review_count": 89,
      "monthly_revenue": 4500.00
    }
  }
}

Update Analytics Asset

Update configuration and settings for an analytics asset.

PATCH /analytics/assets/{asset_id}

Update Analytics Asset Parameters

asset_id (path, required): Analytics asset identifier

Update Analytics Asset Request Body

{
  "name": "Advanced Customer Churn Predictor",
  "description": "Updated ML model with enhanced feature engineering",
  "configuration": {
    "performance_threshold": 0.90,
    "additional_features": ["social_media_engagement", "mobile_app_usage"]
  },
  "pricing": {
    "price": 3.50,
    "free_tier": {
      "requests": 75
    }
  },
  "version_notes": "Added new features and improved accuracy threshold"
}

Update Analytics Asset Response

{
  "data": {
    "asset_id": "asset_123",
    "name": "Advanced Customer Churn Predictor",
    "version": "2.2.0",
    "updated_at": "2025-01-20T17:00:00Z",
    "changes": [
      "Updated performance threshold to 0.90",
      "Added 2 new features",
      "Adjusted pricing to $3.50"
    ],
    "requires_retaining": true,
    "estimated_retraining_time": "45_minutes"
  }
}

Delete Analytics Asset

Archive or permanently delete an analytics asset.

DELETE /analytics/assets/{asset_id}

Delete Analytics Asset Parameters

asset_id (path, required): Analytics asset identifier

Delete Analytics Asset Query Parameters

permanent (optional): Permanently delete (true) or archive (false,
default)

Delete Analytics Asset Response

204 No Content

Analytics Execution

Execute Analytics

Run analytics processing on provided data or connected sources.

POST /analytics/assets/{asset_id}/execute

Execute Analytics Parameters

asset_id (path, required): Analytics asset identifier

Execute Analytics Request Body

{
  "input_data": {
    "customer_id": "cust_12345",
    "transaction_data": {
      "last_purchase_date": "2025-01-15",
      "total_spent": 2450.00,
      "purchase_frequency": 12
    },
    "engagement_data": {
      "email_opens": 8,
      "website_visits": 24,
      "support_tickets": 1
    }
  },
  "parameters": {
    "prediction_horizon": 90,
    "include_confidence_interval": true,
    "include_feature_importance": true
  },
  "output_options": {
    "format": "detailed",
    "include_metadata": true
  }
}

Execute Analytics Response

{
  "data": {
    "execution_id": "exec_789",
    "asset_id": "asset_123",
    "customer_id": "cust_12345",
    "results": {
      "churn_probability": 0.23,
      "risk_level": "low",
      "confidence_interval": {
        "lower": 0.18,
        "upper": 0.28
      },
      "key_factors": [
        {
          "factor": "purchase_frequency",
          "importance": 0.35,
          "direction": "protective"
        },
        {
          "factor": "support_tickets",
          "importance": 0.22,
          "direction": "risk"
        }
      ]
    },
    "metadata": {
      "model_version": "2.1.0",
      "execution_time_ms": 165,
      "data_points_used": 847,
      "prediction_date": "2025-01-20T17:15:00Z"
    }
  }
}

Batch Execute Analytics

Process multiple records in a single request for efficiency.

POST /analytics/assets/{asset_id}/batch-execute

Batch Execute Analytics Parameters

asset_id (path, required): Analytics asset identifier

Batch Execute Analytics Request Body

{
  "batch_data": [
    {
      "id": "batch_001",
      "customer_id": "cust_12345",
      "input_data": {}
    },
    {
      "id": "batch_002", 
      "customer_id": "cust_67890",
      "input_data": {}
    }
  ],
  "parameters": {
    "prediction_horizon": 90,
    "parallel_processing": true
  },
  "callback_url": "https://yourapp.com/webhooks/batch-complete"
}

Batch Execute Analytics Response

{
  "data": {
    "batch_id": "batch_456",
    "asset_id": "asset_123",
    "status": "processing",
    "total_records": 2,
    "estimated_completion": "2025-01-20T17:20:00Z",
    "callback_url": "https://yourapp.com/webhooks/batch-complete",
    "progress_url": "https://api.spartera.com/analytics/batches/batch_456/status"
  }
}

Get Batch Status

Check the status of a batch processing operation.

GET /analytics/batches/{batch_id}/status

Get Batch Status Parameters

batch_id (path, required): Batch processing identifier

Get Batch Status Response

{
  "data": {
    "batch_id": "batch_456",
    "asset_id": "asset_123",
    "status": "completed",
    "progress": {
      "total_records": 2,
      "processed_records": 2,
      "successful_records": 2,
      "failed_records": 0,
      "percentage_complete": 100
    },
    "started_at": "2025-01-20T17:15:00Z",
    "completed_at": "2025-01-20T17:18:00Z",
    "results_url": "https://api.spartera.com/analytics/batches/batch_456/results"
  }
}

Data Source Management

List Data Sources

Get all data sources connected to your analytics assets.

GET /analytics/data-sources

List Data Sources Query Parameters

type (optional): Filter by source type (bigquery, snowflake, etc.)
status (optional): Filter by connection status
asset_id (optional): Filter by associated analytics asset

Response

{
  "data": [
    {
      "source_id": "bigquery_production",
      "name": "Production BigQuery",
      "type": "bigquery",
      "status": "connected",
      "project_id": "my-project-123",
      "dataset": "analytics_dataset",
      "tables": ["customers", "transactions", "events"],
      "connection_details": {
        "region": "us-central1",
        "last_validated": "2025-01-20T16:00:00Z",
        "permissions": "read_only"
      },
      "associated_assets": ["asset_123", "asset_456"],
      "created_at": "2024-06-10T09:00:00Z"
    }
  ],
  "meta": {
    "total": 3,
    "connected": 3,
    "disconnected": 0
  }
}

Connect Data Source

Establish a connection to a new data source.

POST /analytics/data-sources

Connect Data Source Request Body

{
  "name": "Snowflake Analytics Warehouse",
  "type": "snowflake",
  "connection_config": {
    "account": "xy12345.snowflakecomputing.com",
    "warehouse": "ANALYTICS_WH",
    "database": "PROD_DB",
    "schema": "PUBLIC",
    "username": "analytics_user",
    "password": "secure_password",
    "role": "ANALYTICS_ROLE"
  },
  "access_level": "read_only",
  "validation_query": "SELECT COUNT(*) FROM customers LIMIT 1"
}

Connect Data Source Response

{
  "data": {
    "source_id": "snowflake_analytics",
    "name": "Snowflake Analytics Warehouse",
    "type": "snowflake",
    "status": "connecting",
    "connection_test": {
      "status": "passed",
      "latency_ms": 245,
      "tables_discovered": 12
    },
    "security": {
      "encrypted": true,
      "access_level": "read_only",
      "ip_restrictions": "enabled"
    },
    "created_at": "2025-01-20T17:30:00Z"
  }
}

Test Data Source Connection

Validate connectivity and permissions for a data source.

POST /analytics/data-sources/{source_id}/test

Test Data Source Connection Parameters

source_id (path, required): Data source identifier

Test Data Source Connection Response

{
  "data": {
    "source_id": "bigquery_production",
    "test_results": {
      "connectivity": {
        "status": "passed",
        "latency_ms": 125,
        "timestamp": "2025-01-20T17:45:00Z"
      },
      "permissions": {
        "read_access": true,
        "table_discovery": true,
        "schema_access": true
      },
      "data_validation": {
        "sample_query_success": true,
        "row_count_available": true,
        "schema_consistency": true
      }
    },
    "recommendations": [
      "Connection is healthy and ready for use",
      "Consider enabling query caching for better performance"
    ]
  }
}

Model Training and Deployment

Train Analytics Model

Initiate training or retraining of machine learning models.

POST /analytics/assets/{asset_id}/train

Train Analytics Model Parameters

asset_id (path, required): Analytics asset identifier

Train Analytics Model Request Body

{
  "training_config": {
    "algorithm": "xgboost",
    "hyperparameters": {
      "max_depth": 6,
      "learning_rate": 0.1,
      "n_estimators": 100
    },
    "validation_split": 0.2,
    "cross_validation_folds": 5
  },
  "data_config": {
    "training_period": {
      "start_date": "2023-01-01",
      "end_date": "2024-12-31"
    },
    "feature_selection": "auto",
    "target_variable": "churned_90_days"
  },
  "deployment_config": {
    "auto_deploy": true,
    "performance_threshold": 0.90,
    "rollback_on_failure": true
  }
}

Train Analytics Model Response

{
  "data": {
    "training_job_id": "job_789",
    "asset_id": "asset_123",
    "status": "started",
    "estimated_duration": "25_minutes",
    "progress": {
      "current_step": "data_preparation",
      "steps_total": 5,
      "percentage_complete": 20
    },
    "started_at": "2025-01-20T18:00:00Z",
    "estimated_completion": "2025-01-20T18:25:00Z"
  }
}

Get Training Status

Monitor the progress of model training operations.

GET /analytics/training-jobs/{job_id}

Get Training Status Parameters

job_id (path, required): Training job identifier

Get Training Status Response

{
  "data": {
    "training_job_id": "job_789",
    "asset_id": "asset_123",
    "status": "completed",
    "progress": {
      "current_step": "deployment",
      "steps_completed": 5,
      "steps_total": 5,
      "percentage_complete": 100
    },
    "results": {
      "model_performance": {
        "accuracy": 0.93,
        "precision": 0.91,
        "recall": 0.95,
        "f1_score": 0.93
      },
      "deployment_status": "successful",
      "model_version": "2.3.0"
    },
    "started_at": "2025-01-20T18:00:00Z",
    "completed_at": "2025-01-20T18:23:00Z",
    "logs_url": "https://api.spartera.com/analytics/training-jobs/job_789/logs"
  }
}

Analytics Versioning

List Asset Versions

Get version history for an analytics asset.

GET /analytics/assets/{asset_id}/versions

List Asset Versions Parameters

asset_id (path, required): Analytics asset identifier

List Asset Versions Response

{
  "data": [
    {
      "version": "2.3.0",
      "status": "active",
      "created_at": "2025-01-20T18:23:00Z",
      "performance_metrics": {
        "accuracy": 0.93,
        "avg_response_time": 145
      },
      "changes": ["Improved model accuracy", "Added new features"],
      "deployment_date": "2025-01-20T18:25:00Z"
    },
    {
      "version": "2.2.0", 
      "status": "deprecated",
      "created_at": "2025-01-15T14:30:00Z",
      "performance_metrics": {
        "accuracy": 0.92,
        "avg_response_time": 180
      }
    }
  ],
  "meta": {
    "current_version": "2.3.0",
    "total_versions": 8
  }
}

Deploy Specific Version

Deploy a specific version of an analytics asset.

POST /analytics/assets/{asset_id}/versions/{version}/deploy

Deploy Specific Version Parameters

asset_id (path, required): Analytics asset identifier
version (path, required): Version to deploy

Deploy Specific Version Request Body

{
  "deployment_strategy": "blue_green",
  "rollback_threshold": {
    "error_rate": 0.05,
    "response_time": 500
  },
  "notification_webhooks": [
    "https://yourapp.com/webhooks/deployment"
  ]
}

Deploy Specific Version Response

{
  "data": {
    "deployment_id": "deploy_123",
    "asset_id": "asset_123",
    "version": "2.2.0",
    "status": "deploying",
    "strategy": "blue_green",
    "started_at": "2025-01-20T19:00:00Z",
    "estimated_completion": "2025-01-20T19:05:00Z"
  }
}

The analytics endpoints provide comprehensive control over analytics
assets throughout their entire lifecycle, from creation and training
to deployment and ongoing management.