Skip to main content

​
Dashboard API

Retrieve consolidated dashboard data, analytics trends, cost breakdowns, and agent statistics. All endpoints except dashboard health require session authentication.

​
Dashboard data

GET /api/dashboard/data
Requires session authentication. Returns all core dashboard data in a single request. This endpoint uses the standard Node.js runtime and is marked force-dynamic so responses are never statically cached.

​
Response

{
  "userId": "user_abc123",
  "credits": 10,
  "plan": "solo",
  "openclawUrl": "https://openclaw-agent-abc.up.railway.app",
  "openclawInstanceId": "inst_abc123",
  "gatewayToken": "a1b2c3d4e5f6...",
  "agent": {
    "id": "agent_abc123",
    "status": "active",
    "name": "my-agent",
    "tier": "solo"
  },
  "health": {
    "status": "healthy",
    "checks": [
      { "name": "Database", "status": "ok" },
      { "name": "Gateway", "status": "ok" }
    ]
  },
  "meta": {
    "responseTime": 45,
    "cached": false,
    "timestamp": "2026-04-04T12:00:00.000Z"
  }
}
FieldTypeDescription
userIdstringAuthenticated user ID
creditsnumberAvailable referral credits
planstringCurrent subscription plan (for example free, solo, collective, label, network)
openclawUrlstring | nullURL for the user’s OpenClaw instance
openclawInstanceIdstring | nullOpenClaw instance identifier. Falls back to the agent ID when not explicitly set.
gatewayTokenstring | nullEffective gateway token for authenticating with the agent gateway. Falls back to the registration token when no gateway token is set.
agentobject | nullAgent details, or null if no agent exists
agent.idstringAgent identifier
agent.statusstringCurrent agent status
agent.namestringAgent display name
agent.tierstringAgent tier
healthobjectAggregated system health
health.statusstringhealthy when all checks pass, degraded otherwise
health.checksarrayIndividual service check results
health.checks[].namestringService name
health.checks[].statusstringok or down
health.checks[].detailstring | undefinedError detail when the check failed
meta.responseTimenumberServer-side response time in milliseconds
meta.cachedbooleanWhether the response was served from cache
meta.timestampstringISO 8601 timestamp

​
Errors

CodeDescription
401Unauthorized — no valid session
500Failed to fetch dashboard data. The response includes a details field with the error message and a responseTime field.

​
Dashboard analytics

GET /api/dashboard/analytics
Requires session authentication. Returns time-series trends for deployments, skills, and tasks, along with channel activity and top installed skills.

​
Query parameters

ParameterTypeDefaultDescription
rangenumber180Number of days to include in the trend data. Accepted values: 30, 90, 180, 365. Any other value defaults to 180.

​
Response

{
  "overview": {
    "deployedAgents": 3,
    "liveAgents": 2,
    "installedSkills": 8,
    "scheduledTasks": 4,
    "connectedChannels": 2,
    "channelMessages": 156
  },
  "trend": [
    {
      "label": "Jan",
      "deployments": 1,
      "skills": 3,
      "tasks": 2
    }
  ],
  "topSkills": [
    { "name": "weather", "installs": 3 }
  ],
  "channels": [
    {
      "name": "Webchat",
      "messages": 85,
      "lastActive": "2026-04-04T11:30:00.000Z",
      "status": "connected"
    },
    {
      "name": "Telegram",
      "messages": 71,
      "lastActive": "2026-04-04T10:15:00.000Z",
      "status": "connected"
    }
  ],
  "source": {
    "gateway": "live",
    "sessions": "live"
  }
}
FieldTypeDescription
overview.deployedAgentsnumberTotal number of agents
overview.liveAgentsnumberAgents with status active or running
overview.installedSkillsnumberTotal enabled skills
overview.scheduledTasksnumberTotal scheduled tasks
overview.connectedChannelsnumberChannels with status connected
overview.channelMessagesnumberTotal messages across all channels
trendarrayMonthly trend buckets within the requested range
trend[].labelstringMonth abbreviation (for example Jan, Feb)
trend[].deploymentsnumberAgents created in this month
trend[].skillsnumberSkills installed in this month
trend[].tasksnumberTasks created in this month
topSkillsarrayUp to 6 most-installed skills
topSkills[].namestringSkill name
topSkills[].installsnumberNumber of installs
channelsarrayPer-channel activity summary
channels[].namestringChannel display name (Webchat, Telegram, Discord, WhatsApp, iMessage)
channels[].messagesnumberMessage count for this channel
channels[].lastActivestring | nullISO 8601 timestamp of last activity
channels[].statusstringChannel status: connected, not-configured, or unreachable
source.gatewaystringGateway data source: live or unreachable
source.sessionsstringSessions data source: live or unavailable

​
Errors

CodeDescription
401Unauthorized — no valid session
500Failed to fetch analytics

​
Dashboard bootstrap

GET /api/dashboard/bootstrap
Requires session authentication. Returns lightweight initialization data for the dashboard, including referral credits, plan information, and OpenClaw connection details. The gatewayToken is the authenticated user’s own token, enabling automatic pairing with their agent instance.

​
Response

{
  "credits": 10,
  "referralCode": "REF_abc123",
  "referralCount": 3,
  "plan": "solo",
  "openclawUrl": "https://openclaw-agent-abc.up.railway.app",
  "openclawInstanceId": "inst_abc123",
  "gatewayToken": "a1b2c3d4e5f6..."
}
FieldTypeDescription
creditsnumberAvailable referral credits
referralCodestring | nullUser’s referral code
referralCountnumberNumber of successful referrals
planstring | nullCurrent subscription plan
openclawUrlstring | nullOpenClaw instance URL
openclawInstanceIdstring | nullOpenClaw instance identifier
gatewayTokenstring | nullThe authenticated user’s gateway token for auto-pairing with their agent instance, or null if no token is registered

​
Errors

CodeDescription
401Unauthorized — no valid session

​
Dashboard cost

GET /api/dashboard/cost
Requires session authentication. Returns cost breakdown for the current billing period, including per-agent costs, daily cost trends, and model usage breakdown. Combines subscription plan costs from the database with AI token usage data from the backend metrics service when available.

​
Query parameters

ParameterTypeDefaultDescription
periodstring7dCost period to retrieve. Accepted values: 7d, 30d, mtd (month to date).

​
Response

{
  "period": "7d",
  "summary": {
    "totalCost": 6.77,
    "totalTokens": 45000,
    "totalCalls": 120,
    "avgCostPerCall": 0.0042
  },
  "agents": [
    {
      "name": "my-agent",
      "tokens": 25000,
      "cost": 3.50,
      "calls": 80,
      "avgCostPerCall": 0.0044,
      "model": "solo"
    }
  ],
  "daily": [
    {
      "date": "Mar 29",
      "cost": 0.97,
      "tokens": 6500
    }
  ],
  "modelBreakdown": [
    {
      "model": "solo",
      "percent": 100,
      "cost": 6.77
    }
  ],
  "isMockData": false,
  "plan": "solo",
  "planMonthlyCost": 29,
  "agentCount": 2,
  "activeAgents": 1
}
FieldTypeDescription
periodstringRequested cost period
summary.totalCostnumberTotal cost for the period
summary.totalTokensnumberTotal AI tokens consumed
summary.totalCallsnumberTotal AI API calls
summary.avgCostPerCallnumberAverage cost per AI call
agentsarrayPer-agent cost breakdown
agents[].namestringAgent name or identifier
agents[].tokensnumberTokens consumed by this agent
agents[].costnumberTotal cost attributed to this agent
agents[].callsnumberNumber of AI calls made by this agent
agents[].avgCostPerCallnumberAverage cost per call for this agent
agents[].modelstringModel or plan tier used
dailyarrayDaily cost breakdown
daily[].datestringDate label (for example Mar 29)
daily[].costnumberCost for this day
daily[].tokensnumberTokens used on this day
modelBreakdownarrayCost breakdown by model
modelBreakdown[].modelstringModel identifier
modelBreakdown[].percentnumberPercentage of total cost
modelBreakdown[].costnumberCost attributed to this model
isMockDatabooleanAlways false. Indicates that the response uses real data.
planstringUser’s current plan
planMonthlyCostnumberMonthly cost of the subscription plan in USD
agentCountnumberTotal number of agents
activeAgentsnumberNumber of agents with status active or running
When the backend metrics service is unavailable, token usage and AI call data default to 0. The plan-based subscription cost is always available from the database.

​
Plan pricing

PlanMonthly cost
solo / starter / underground$29
collective / pro$69
label / scale$149
network / enterprise$499

​
Errors

CodeDescription
401Unauthorized — no valid session
500Failed to fetch cost data

​
Dashboard stats

GET /api/dashboard/stats
Requires session authentication. Returns agent, skill, and task counts for the authenticated user, including plan-based agent limits.

​
Response

{
  "agents": {
    "active": 1,
    "total": 2,
    "limit": 1,
    "newToday": 0
  },
  "skills": {
    "installed": 5
  },
  "tasks": {
    "total": 3
  }
}
FieldTypeDescription
agents.activenumberNumber of agents with status active
agents.totalnumberTotal number of agents
agents.limitnumberMaximum agents allowed by the user’s plan
agents.newTodaynumberAgents created today
skills.installednumberTotal installed skills across all agents
tasks.totalnumberTotal scheduled tasks across all agents

​
Plan agent limits

PlanAgent limit
free / solo / starter1
pro / collective3
scale / label10
enterprise / network100

​
Errors

On failure, the endpoint returns HTTP 200 with zeroed fallback data instead of an error status code: 
{
  "agents": { "active": 0, "total": 0, "limit": 1, "newToday": 0 },
  "skills": { "installed": 0 },
  "tasks": { "total": 0 }
}
CodeDescription
401Unauthorized — no valid session, or user not found (returns 404)