Skip to content

Portfolio API

Executive-level portfolio overview, KPIs, trends, and process health metrics.

Overview

The Portfolio API provides high-level analytics across all process definitions in your Camunda environment. It's designed for management dashboards, executive reporting, and portfolio-wide monitoring.

Base Path: /portfolio

Required Permission: portfolio_data

Endpoints

Get Portfolio Overview

Retrieve comprehensive portfolio statistics and process health metrics.

GET /portfolio/api/overview

Headers:

Authorization: Bearer <token>

Response: 200 OK

{
  "success": true,
  "overview": [
    {
      "process_key": "order-to-cash",
      "process_name": "Order to Cash",
      "latest_version": 3,
      "active_instances": 145,
      "open_incidents": 5,
      "started_this_month": 234,
      "started_last_30_days": 267,
      "completed_last_30_days": 251,
      "total_completed_all_time": 5432,
      "avg_duration_seconds": 3600,
      "success_rate_30d": 94.5,
      "health_score": 87,
      "incident_rate": 3.2,
      "completion_rate_30d": 94.0,
      "throughput_30d": 8.37
    }
  ],
  "summary_stats": {
    "total_processes": 12,
    "active_instances": 1247,
    "open_incidents": 23,
    "started_this_month": 2341,
    "started_last_30_days": 2567,
    "completed_last_30_days": 2489,
    "processes_at_risk": 3,
    "avg_completion_time": 4523.5,
    "success_rate_30d": 96.2
  },
  "top_issues": [
    {
      "process_key": "invoice-processing",
      "process_name": "Invoice Processing",
      "open_incidents": 8,
      "incident_rate": 5.2,
      "health_score": 72
    }
  ],
  "timestamp": "2025-01-15T10:30:00.123456"
}

Field Descriptions:

Field Type Description
process_key string Unique process identifier
process_name string Human-readable process name
latest_version integer Most recent deployed version
active_instances integer Currently running instances
open_incidents integer Unresolved incidents
started_this_month integer Instances started in current month
started_last_30_days integer Instances started in last 30 days
completed_last_30_days integer Instances completed in last 30 days
total_completed_all_time integer Total completed instances (all-time)
avg_duration_seconds float Average completion time in seconds
success_rate_30d float Success rate percentage (last 30 days)
health_score integer Overall health score (0-100)
incident_rate float Incident rate percentage
completion_rate_30d float Completion rate percentage
throughput_30d float Average instances per day (last 30 days)

Example:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8088/portfolio/api/overview

import requests

headers = {'Authorization': f'Bearer {token}'}
response = requests.get(
    'http://localhost:8088/portfolio/api/overview',
    headers=headers
)

if response.status_code == 200:
    data = response.json()
    print(f"Total processes: {data['summary_stats']['total_processes']}")
    print(f"Portfolio health: {data['summary_stats']['success_rate_30d']}%")

    # Find processes at risk
    at_risk = [p for p in data['overview'] if p['health_score'] < 75]
    print(f"Processes needing attention: {len(at_risk)}")

const response = await fetch('http://localhost:8088/portfolio/api/overview', {
  headers: { 'Authorization': `Bearer ${token}` }
});

const data = await response.json();
console.log(`Total processes: ${data.summary_stats.total_processes}`);
console.log(`Portfolio health: ${data.summary_stats.success_rate_30d}%`);

// Find processes at risk
const atRisk = data.overview.filter(p => p.health_score < 75);
console.log(`Processes needing attention: ${atRisk.length}`);

Retrieve 12-month historical trend data for instances and incidents.

GET /portfolio/api/trends

Headers:

Authorization: Bearer <token>

Response: 200 OK

{
  "success": true,
  "trend_chart_data": {
    "labels": [
      "2024-02",
      "2024-03",
      "2024-04",
      "2024-05",
      "2024-06",
      "2024-07",
      "2024-08",
      "2024-09",
      "2024-10",
      "2024-11",
      "2024-12",
      "2025-01"
    ],
    "series": [
      {
        "name": "Instances Started",
        "data": [1234, 1456, 1589, 1678, 1834, 1923, 2012, 2145, 2267, 2389, 2456, 2341]
      },
      {
        "name": "Incidents Created",
        "data": [45, 52, 48, 67, 71, 65, 58, 62, 54, 49, 51, 47]
      }
    ]
  },
  "timestamp": "2025-01-15T10:30:00"
}

Use Cases:

  • Display trend charts on executive dashboards
  • Identify seasonal patterns
  • Track incident rate changes over time
  • Monitor growth in process automation

Example:

import matplotlib.pyplot as plt

response = requests.get(
    'http://localhost:8088/portfolio/api/trends',
    headers={'Authorization': f'Bearer {token}'}
)

data = response.json()['trend_chart_data']

# Plot trends
plt.figure(figsize=(12, 6))
for series in data['series']:
    plt.plot(data['labels'], series['data'], label=series['name'], marker='o')

plt.xlabel('Month')
plt.ylabel('Count')
plt.title('Portfolio Trends (12 Months)')
plt.legend()
plt.xticks(rotation=45)
plt.tight_layout()
plt.show()

Get Portfolio Metrics (Prometheus)

Export portfolio metrics in Prometheus format for Grafana integration.

GET /portfolio/overview/metrics

Headers:

Authorization: Bearer <token>

Response: 200 OK

Content-Type: text/plain; charset=utf-8

# HELP camunda_portfolio_total_processes Total processes in portfolio
# TYPE camunda_portfolio_total_processes gauge
camunda_portfolio_total_processes 12

# HELP camunda_portfolio_active_instances Total active instances across portfolio
# TYPE camunda_portfolio_active_instances gauge
camunda_portfolio_active_instances 1247

# HELP camunda_portfolio_open_incidents Total open incidents across portfolio
# TYPE camunda_portfolio_open_incidents gauge
camunda_portfolio_open_incidents 23

# HELP camunda_process_health_score Process health score
# TYPE camunda_process_health_score gauge
camunda_process_health_score{process="order_to_cash",version="3"} 87
camunda_process_health_score{process="invoice_processing",version="2"} 72

# HELP camunda_process_active_instances Active instances per process
# TYPE camunda_process_active_instances gauge
camunda_process_active_instances{process="order_to_cash",version="3"} 145
camunda_process_active_instances{process="invoice_processing",version="2"} 89

Grafana Configuration:

# prometheus.yml
scrape_configs:
  - job_name: 'champa-portfolio'
    scrape_interval: 5m
    metrics_path: /portfolio/overview/metrics
    bearer_token: 'YOUR_API_TOKEN'
    static_configs:
      - targets: ['champa-intelligence:8088']

Example Grafana Queries:

# Total active instances
camunda_portfolio_active_instances

# Processes with health score < 80
camunda_process_health_score < 80

# Incident rate by process
rate(camunda_process_open_incidents[1h])

# Top 5 processes by throughput
topk(5, camunda_process_throughput_30d)

Next Steps

Support

For portfolio API questions: