Platform Intelligence API

Public endpoint that aggregates real-time platform statistics for the AINative Intelligence Dashboard at ainative.studio/intelligence. No authentication required.

---

Table of Contents

• Endpoints
• Response Schema
• Data Sources
• How the Dashboard Consumes This

---

Endpoints

GET /api/v1/public/platform/intelligence

Full platform intelligence response with stats, agent events, data lake analytics, and ads performance.

Auth: None (public endpoint)

Route registration: Mounted via the public router at prefix /platform, defined in app.api.routers.public.

Example request:

curl https://api.ainative.studio/api/v1/public/platform/intelligence

Example response:

{
  "stats": {
    "uptime_pct": 99.97,
    "requests_total": 642000,
    "agents_active": 14,
    "models_served": 8,
    "memory_queries_today": 312,
    "tasks_completed_today": 47,
    "tokens_processed_today": 1580000,
    "improvement_loops": 89,
    "last_updated": "2026-06-01T14:30:00+00:00",
    "latency_p99_ms": 245.50
  },
  "agent_events": [
    {
      "id": "machine-dev-mac",
      "agent": "Dev Mac",
      "role": "Machine",
      "action": "12 agents online",
      "target": "45 improvement loops",
      "timestamp": "2m ago",
      "status": "running"
    },
    {
      "id": "agent-sage",
      "agent": "Sage",
      "role": "Backend",
      "action": "merged PR #3450",
      "target": "",
      "timestamp": "15m ago",
      "status": "completed"
    }
  ],
  "lake": {
    "agent_runs_30d": 1240,
    "agent_success_rate_pct": 94.2,
    "api_requests_30d": 580000,
    "total_credits_30d": 12450.75,
    "loop_quality": {
      "overall_success_rate_pct": 91.5,
      "improving": true,
      "trend": [
        {"date": "2026-05-25", "success_rate": 89.0, "total_runs": 42}
      ],
      "source": "lake"
    },
    "packages": {
      "total_downloads": 52000,
      "top_packages": [
        {"name": "zerodb-mcp", "ecosystem": "pypi", "downloads": 18500}
      ],
      "source": "lake"
    },
    "business": {
      "mrr_trend_7d": [
        {"date": "2026-05-31", "amount_usd": 125.00}
      ],
      "stripe_events_7d": 34,
      "emails_delivered_7d": 210,
      "open_pipeline_value": 15000.00,
      "open_deals_count": 3,
      "commerce_revenue_7d": 450.00,
      "source": "lake"
    },
    "rlhf_quality_score_7d": 0.8234,
    "regional_economy": {
      "unemployment_rate": 4.2,
      "fred_series_count": 6,
      "federal_awards_ytd": 125000.00,
      "federal_awards_count": 8,
      "edd_total_employment": 132000.0,
      "source": "lake"
    },
    "source": "lake"
  },
  "ads": {
    "total_spend": 0,
    "total_clicks": 1420,
    "total_impressions": 0,
    "total_conversions": 3,
    "avg_cpc": 0,
    "ctr": 0,
    "campaigns_active": 4,
    "top_keyword": "platform activity",
    "top_keyword_conversions": 3,
    "source": "db_proxy"
  },
  "ok": true
}

---

GET /api/v1/public/platform/intelligence/summary

Lightweight aggregate summary optimized for fast polling.

Auth: None

curl https://api.ainative.studio/api/v1/public/platform/intelligence/summary

Response fields:

Field	Type	Description
agent_runs_today	int	Agent tasks completed today (from lake)
agent_runs_week	int	Agent tasks completed this week
api_calls_today	int	API requests today
billing_revenue_week	float	Credits consumed this week
top_packages_downloads	int	Total package downloads (30d)
generated_at	string	ISO timestamp
source	string	"lake", "lake_empty", or "unavailable"

---

GET /api/v1/public/platform/intelligence/packages

npm and PyPI download statistics from the data lake.

Auth: None

Query parameters:

Parameter	Type	Default	Description
days	int	30	Days to aggregate (1-90)

curl "https://api.ainative.studio/api/v1/public/platform/intelligence/packages?days=30"

Response fields:

Field	Type	Description
total_downloads	int	Sum of all package downloads
packages	list	Sorted by downloads desc: {name, ecosystem, downloads}
days	int	Aggregation window
generated_at	string	ISO timestamp
source	string	"lake", "lake_empty", or "unavailable"

---

Response Schema

PlatformIntelligenceResponse (top level)

Field	Type	Description
stats	PlatformIntelligenceStats	Core platform metrics
agent_events	list[AgentEvent]	Recent agent activity feed (up to 20 events)
lake	LakeAnalytics or null	Historical analytics from MinIO data lake
ads	AdsStats or null	Google Ads campaign performance proxy
ok	bool	Always true on success

PlatformIntelligenceStats

Field	Type	Source	Description
uptime_pct	float	mcp_request_logs (primary), kong_usage_metrics (secondary)	7-day uptime derived from 5xx error rate. Fallback: 99.97
requests_total	int	mcp_request_logs	Total API requests (all time)
agents_active	int	agent_heartbeat_executions + agent_deployments + peer_swarm_heartbeat	Count of active agents across all sources
models_served	int	/api/v1/models endpoint	Number of AI models available
memory_queries_today	int	mcp_request_logs (endpoint LIKE %/memory/%)	ZeroMemory API calls today
tasks_completed_today	int	agent_run_log + swarm_tasks + peer_swarm_heartbeat	Completed agent tasks today
tokens_processed_today	int	platform/llm_token_usage lake partition (primary), credits x 1000 (fallback)	LLM tokens processed today
improvement_loops	int	agent_run_log + agent_traces + peer_swarm_heartbeat + mcp_request_logs	Memory consolidation, reflection, and decay operations
last_updated	string	computed	ISO timestamp of when stats were generated
latency_p99_ms	float or null	mcp_request_logs (7-day p99 percentile)	p99 API latency in milliseconds

AgentEvent

Field	Type	Description
id	string	Unique event identifier (prefixed: agent-, machine-, cloud-, hb-)
agent	string	Friendly agent name (e.g., "Cody", "Sage", "Aurora")
role	string	Agent role (e.g., "Orchestrator", "Backend", "QA")
action	string	What the agent did
target	string	Target of the action (may be empty)
timestamp	string	Human-readable relative time (e.g., "5m ago", "2h ago")
status	string	"completed", "running", or "queued"

LakeAnalytics

Field	Type	Description
agent_runs_30d	int	Total agent runs in the last 30 days
agent_success_rate_pct	float	Agent success rate over 30 days
api_requests_30d	int	Total API requests over 30 days
total_credits_30d	float	Total credits consumed over 30 days
loop_quality	LoopQualityTrend	Recursive improvement loop quality trend (14d)
packages	PackageStats	npm + PyPI download stats (30d)
business	BusinessSignals or null	Revenue, pipeline, and email delivery signals
rlhf_quality_score_7d	float or null	Average RLHF reward score (7d)
regional_economy	RegionalEconomicSignals or null	Santa Cruz County open-data signals
source	string	"lake", "lake_empty", or "unavailable"

BusinessSignals

Field	Type	Description
mrr_trend_7d	list	Daily revenue trend: {date, amount_usd}
stripe_events_7d	int	Total Stripe webhook events in 7 days
emails_delivered_7d	int	Emails successfully delivered
open_pipeline_value	float	Sum of open deal values (ZeroPipeline)
open_deals_count	int	Number of open deals
commerce_revenue_7d	float	ZeroCommerce order revenue
source	string	"lake" or "unavailable"

RegionalEconomicSignals

Field	Type	Description
unemployment_rate	float or null	Latest FRED CACRUZ0URN series value
fred_series_count	int	Distinct FRED economic series in the lake
federal_awards_ytd	float	USAspending total federal award amount YTD
federal_awards_count	int	Number of federal awards
edd_total_employment	float or null	Latest QCEW all-industry employment
source	string	"lake" or "unavailable"

AdsStats

Field	Type	Description
total_spend	float	Ad spend (0 when Google Ads API unavailable)
total_clicks	int	Proxied from today's API request count
total_impressions	int	0 when unavailable
total_conversions	int	New user signups today (excluding test/trial accounts)
avg_cpc	float	Average cost per click
ctr	float	Click-through rate
campaigns_active	int	Active campaign count
top_keyword	string	Top performing keyword
top_keyword_conversions	int	Conversions for top keyword
source	string	"db_proxy", "ads_report", or "unavailable"

---

Data Sources

The intelligence endpoint aggregates data from multiple database tables and external services. Each data source is queried independently with its own error handling, so a failure in one source does not block the others.

Database Tables

Table	Data Pulled	Used For
mcp_request_logs	Total request count, credits consumed, memory query count, uptime (5xx rate), p99 latency, improvement loop endpoints	requests_total, memory_queries_today, uptime_pct, latency_p99_ms, improvement_loops
agent_run_log	Per-agent latest activity, task completion count, improvement summaries	tasks_completed_today, agent_events, improvement_loops
peer_swarm_heartbeat	Active agent count and improvement loops from peer machines (10-min staleness window)	agents_active, improvement_loops, machine-level events
agent_heartbeat_executions	Distinct agents with successful runs in last 2 hours	agents_active, heartbeat events
agent_deployments	Running Agent Cloud deployments	agents_active (cloud)
agent_traces	Recent Agent Cloud operations, memory/reflect/consolidate traces	Cloud agent events, improvement_loops
swarm_tasks	Completed swarm tasks today	tasks_completed_today
kong_usage_metrics	Error rate, p99 latency (secondary source, rarely populated)	uptime_pct fallback
users	New signups today	ads.total_conversions

MinIO Data Lake (Parquet partitions)

Partition	Data	Used For
agent_run_log	30-day agent run history	lake.agent_runs_30d, lake.agent_success_rate_pct
mcp_request_logs	30-day API request history	lake.api_requests_30d, lake.total_credits_30d
package_stats	npm + PyPI download counts	lake.packages
rlhf_signals	RLHF reward scores	lake.rlhf_quality_score_7d
stripe_events	Stripe webhook events	lake.business.mrr_trend_7d, lake.business.stripe_events_7d
external/email	Email delivery events	lake.business.emails_delivered_7d
business/crm/deals	ZeroPipeline deal data	lake.business.open_pipeline_value
business/commerce/orders	ZeroCommerce orders	lake.business.commerce_revenue_7d
external/scc/fred_indicators	FRED economic indicators	lake.regional_economy.unemployment_rate
external/scc/federal_awards	USAspending awards	lake.regional_economy.federal_awards_ytd
external/scc/edd_labor	EDD QCEW labor data	lake.regional_economy.edd_total_employment
platform/llm_token_usage	Daily LLM token counts	stats.tokens_processed_today

External HTTP Calls

Service	Purpose
GET /api/v1/models (self)	Count available AI models for stats.models_served
GitHub API (api.github.com)	Fallback agent events from recent PRs across AINative-Studio repos (used when all DB event sources are empty)

---

How the Dashboard Consumes This

The Intelligence Dashboard at ainative.studio/intelligence is a Next.js page in the frontend application.

Polling behavior

The page fetches GET /api/v1/public/platform/intelligence on load and refreshes on a regular interval. No authentication is needed since the endpoint is mounted under the public router.

Agent roster

The endpoint maintains a known agent roster that maps agent IDs to friendly names and roles:

Agent ID	Display Name	Role
main	Cody	Orchestrator
sage	Sage	Backend
aurora	Aurora	QA
nova	Nova	Security
atlas	Atlas	Infra
lyra	Lyra	Frontend
luma	Luma	Documentation
helios	Helios	Performance
vega	Vega	Analytics
pr-review-bot	PR Bot	Code Review
sales-agent	Sales	Sales
vp-marketing	Marketing	Marketing
scout	Scout	Intelligence

Agents that have no recent agent_run_log entries are shown with status "queued" and action "idle -- awaiting task".

Event priority

Agent events are assembled from multiple sources in priority order:

1. Heartbeat executions (agent_heartbeat_executions) -- real cron execution results with success/fail status
2. Peer swarm events (peer_swarm_heartbeat + agent_run_log) -- per-agent activity cards plus machine-level summaries
3. Run log events (agent_run_log) -- individual task completions
4. Agent Cloud events (agent_traces) -- cloud-deployed agent operations
5. GitHub PR fallback -- recent pull requests across AINative-Studio repos, used when all DB sources are empty

The combined list is truncated to 20 events.

Staleness handling

• peer_swarm_heartbeat entries older than 600 seconds (configurable via PEER_HEARTBEAT_MAX_AGE_SECS) are ignored.
• agent_heartbeat_executions uses a 2-hour window.
• agent_run_log and agent_traces use 6-12 hour windows depending on the query.
• When no heartbeat data is available, agents_active falls back to the count of configured agents (currently 11).

Uptime calculation

Uptime is derived from mcp_request_logs over a 7-day window:

uptime_pct = 100.0 - (100.0 * count(status_code >= 500) / count(*))

Values outside the range [90, 100] are discarded and the system falls back to kong_usage_metrics or a static fallback of 99.97%.

Lake data availability

The lake field is null when the MinIO data lake has no exported data. Each sub-section (loop_quality, packages, business, regional_economy) has its own source field indicating whether real lake data was available or not. The top-level lake.source is "lake" if any sub-source has data, "lake_empty" if all partitions are empty, and the entire field is omitted if the lake query module fails to import.