DataPulse Analytics | REST API Reference

API Overview

The DataPulse Analytics REST API provides programmatic access to our advanced analytics engine, customer intelligence platform, and machine learning models. All requests and responses use JSON format.

Rate Limits: 1,000 requests/minute for Standard tier, 5,000 requests/minute for Enterprise tier. Exceeding limits returns 429 Too Many Requests.

Base URL & Environments

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

PRODUCTION

https://api.datapulse.io/v1

SANDBOX

https://sandbox-api.datapulse.io/v1

Authentication

DataPulse uses API keys for authentication. You can manage your keys in the Developer Dashboard.

Header

Authorization: Bearer dp_live_sk_8x92mK4vL1pQ7nR3zW5yJ2hG6fD0sA

Security Note: Never expose your secret keys in client-side code or public repositories. Use environment variables to store credentials securely.

Analytics Engine

Query aggregated metrics, run ad-hoc analytical queries, and retrieve real-time KPI summaries.

GET /analytics/summary

Retrieve KPI Summary

Fetches high-level business metrics aggregated over the specified time window. Supports multiple business verticals.

Parameter	Type	Description
period	string	Time range: `7d`, `30d`, `90d`, `1y`
vertical	string	Business domain: `retail`, `saaS`, `finance`

Response 200

{
  "data": {
    "revenue": 2845000,
    "active_users": 18420,
    "conversion_rate": 0.042,
    "churn_risk": "low",
    "trend": "upward",
    "period": "30d"
  },
  "meta": {
    "generated_at": "2025-01-15T08:30:00Z",
    "cache_hit": true
  }
}

POST /analytics/query

Run Ad-Hoc Query

Execute custom analytical queries against your dataset. Returns structured results with execution metadata.

Parameter	Type	Description
sqlRequired	string	SQL-like query string (sandbox validated)
limit	integer	Max rows to return (default: 100, max: 10000)

Request Body

{
  "sql": "SELECT region, SUM(revenue) FROM transactions GROUP BY region ORDER BY revenue DESC",
  "limit": 50
}

Customer Data

Access unified customer profiles, behavioral segments, and lifetime value predictions.

GET /customers/{id}/profile

Get Customer Profile

Retrieves the unified customer profile including engagement metrics, segments, and CLV prediction.

Parameter	Type	Description
idRequired	string	Customer UUID or external ID

Response 200

{
  "customer_id": "cust_92f8a3b1",
  "segments": ["high_value", "early_adopter"],
  "lifetime_value": 4820.50,
  "last_interaction": "2025-01-14T16:22:00Z",
  "churn_probability": 0.12
}

ML Predictions

Leverage pre-trained models for forecasting, anomaly detection, and predictive scoring.

POST /models/predict

Run Prediction

Submits feature data to a deployed model and returns prediction scores with confidence intervals.

Parameter	Type	Description
model_idRequired	string	Deployed model identifier
featuresRequired	object	Key-value pairs of input features

Response 200

{
  "prediction": "churn_likely",
  "confidence": 0.87,
  "reasons": ["declining_engagement", "support_ticket_spike"],
  "model_version": "v3.2.1"
}

Report Generation

Programmatically generate, schedule, and export analytical reports.

POST /reports/export

Export Report

Generates a downloadable report in CSV, PDF, or Excel format based on query parameters or report templates.

Request Body

{
  "template_id": "tmpl_q3_performance",
  "format": "pdf",
  "include_charts": true,
  "date_range": { "start": "2024-10-01", "end": "2024-12-31" }
}

Error Handling

DataPulse uses conventional HTTP response codes to indicate success or failure of requests.

Code	Meaning	Resolution
`400`	Bad Request	Invalid syntax or missing required parameters
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Insufficient permissions for this endpoint
`404`	Not Found	Resource or endpoint does not exist
`429`	Too Many Requests	Rate limit exceeded. Retry after `Retry-After` header
`500`	Internal Error	Server-side issue. Contact support with trace ID