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"
  }
}

Field	Type	Description
`userId`	string	Authenticated user ID
`credits`	number	Available referral credits
`plan`	string	Current subscription plan (for example `free`, `solo`, `collective`, `label`, `network`)
`openclawUrl`	string \| null	URL for the user’s OpenClaw instance. Used as the base origin for control UI links (chat, skills, config views). When `null`, control UI links fall back to the platform default gateway URL. See control UI URL resolution.
`openclawInstanceId`	string \| null	OpenClaw instance identifier. Falls back to the agent ID when not explicitly set.
`gatewayToken`	string \| null	Effective gateway token for authenticating with the agent gateway. Falls back to the registration token when no gateway token is set. Passed in the control UI URL hash fragment for automatic authentication.
`agent`	object \| null	Agent details, or `null` if no agent exists
`agent.id`	string	Agent identifier
`agent.status`	string	Current agent status
`agent.name`	string	Agent display name
`agent.tier`	string	Agent tier
`health`	object	Aggregated system health
`health.status`	string	`healthy` when all checks pass, `degraded` otherwise
`health.checks`	array	Individual service check results
`health.checks[].name`	string	Service name
`health.checks[].status`	string	`ok` or `down`
`health.checks[].detail`	string \| undefined	Error detail when the check failed
`meta.responseTime`	number	Server-side response time in milliseconds
`meta.cached`	boolean	Whether the response was served from cache
`meta.timestamp`	string	ISO 8601 timestamp

Errors

Code	Description
401	Unauthorized — no valid session
500	Failed 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

Parameter	Type	Default	Description
`range`	number	`180`	Number 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"
  }
}

Field	Type	Description
`overview.deployedAgents`	number	Total number of agents
`overview.liveAgents`	number	Agents with status `active` or `running`
`overview.installedSkills`	number	Total enabled skills
`overview.scheduledTasks`	number	Total scheduled tasks
`overview.connectedChannels`	number	Channels with status `connected`
`overview.channelMessages`	number	Total messages across all channels
`trend`	array	Monthly trend buckets within the requested range
`trend[].label`	string	Month abbreviation (for example `Jan`, `Feb`)
`trend[].deployments`	number	Agents created in this month
`trend[].skills`	number	Skills installed in this month
`trend[].tasks`	number	Tasks created in this month
`topSkills`	array	Up to 6 most-installed skills
`topSkills[].name`	string	Skill name
`topSkills[].installs`	number	Number of installs
`channels`	array	Per-channel activity summary
`channels[].name`	string	Channel display name (`Webchat`, `Telegram`, `Discord`, `WhatsApp`, `iMessage`)
`channels[].messages`	number	Message count for this channel
`channels[].lastActive`	string \| null	ISO 8601 timestamp of last activity
`channels[].status`	string	Channel status: `connected`, `not-configured`, or `unreachable`
`source.gateway`	string	Gateway data source: `live` or `unreachable`
`source.sessions`	string	Sessions data source: `live` or `unavailable`

Errors

Code	Description
401	Unauthorized — no valid session
500	Failed to fetch analytics

Dashboard bootstrap

GET /api/dashboard/bootstrap

Requires session authentication. Returns lightweight initialization data for the dashboard, including referral credits, plan information, OpenClaw connection details, and community reward status. 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...",
  "communityRewards": {
    "connected": true,
    "walletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "claimed": true,
    "currentTier": {
      "id": "builder",
      "label": "Builder",
      "credits": 100,
      "minBalance": 10000
    },
    "balanceUi": 15000,
    "creditsClaimed": 100,
    "claimedAt": "2026-04-10T12:00:00.000Z",
    "availability": "live",
    "detail": null
  }
}

Field	Type	Description
`credits`	number	Available referral credits
`referralCode`	string \| null	User’s referral code
`referralCount`	number	Number of successful referrals
`plan`	string \| null	Current subscription plan
`openclawUrl`	string \| null	OpenClaw instance URL. Used as the base origin for control UI links instead of the platform default.
`openclawInstanceId`	string \| null	OpenClaw instance identifier
`gatewayToken`	string \| null	The authenticated user’s gateway token for auto-pairing with their agent instance, or `null` if no token is registered. Included in control UI URL hash fragments for automatic authentication.
`communityRewards`	object	Community reward status for the authenticated user. See fields below.
`communityRewards.connected`	boolean	`true` if the user has linked a Solana wallet for rewards
`communityRewards.walletAddress`	string \| null	The linked Solana wallet address, or `null` if not connected
`communityRewards.claimed`	boolean	`true` if the user has already claimed community rewards
`communityRewards.currentTier`	object \| null	The reward tier matching the wallet’s current balance, or `null` if below all thresholds
`communityRewards.currentTier.id`	string	Tier identifier (`whale`, `builder`, or `holder`)
`communityRewards.currentTier.label`	string	Tier display name
`communityRewards.currentTier.credits`	number	Credits granted at this tier
`communityRewards.currentTier.minBalance`	number	Minimum token balance required for this tier
`communityRewards.balanceUi`	number \| null	Human-readable token balance, or `null` when unavailable
`communityRewards.creditsClaimed`	number	Total credits claimed through community rewards (0 if unclaimed)
`communityRewards.claimedAt`	string \| null	ISO 8601 timestamp of when the claim was made, or `null`
`communityRewards.availability`	string	`"live"` when Solana RPC is reachable, `"degraded"` when it is not
`communityRewards.detail`	string \| null	Human-readable explanation when `availability` is `"degraded"`

When the Solana RPC endpoint is temporarily unreachable, the communityRewards field degrades gracefully instead of failing the entire bootstrap request. The availability field changes to "degraded" and detail describes the issue. Balance and tier data may be unavailable in this state.

Errors

Code	Description
401	Unauthorized — 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

Parameter	Type	Default	Description
`period`	string	`7d`	Cost 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
  },
  "quota": {
    "monthlyTokens": 2000000,
    "usedTokens": 45000,
    "percent": 2,
    "overageWarning": false,
    "nextPlan": "collective"
  },
  "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
}

Field	Type	Description
`period`	string	Requested cost period
`summary.totalCost`	number	Total cost for the period
`summary.totalTokens`	number	Total AI tokens consumed
`summary.totalCalls`	number	Total AI API calls
`summary.avgCostPerCall`	number	Average cost per AI call
`quota`	object	Monthly token quota and usage
`quota.monthlyTokens`	number	Monthly token quota for the user’s plan (input + output combined)
`quota.usedTokens`	number	Tokens used month-to-date. For `mtd` period, uses actual totals; for other periods, scales period tokens to the current month.
`quota.percent`	number	Percentage of monthly quota used (0–100)
`quota.overageWarning`	boolean	`true` when usage is at or above 80% of the monthly quota
`quota.nextPlan`	string \| null	Suggested upgrade plan when approaching quota limits, or `null` if already on the highest tier
`agents`	array	Per-agent cost breakdown
`agents[].name`	string	Agent name or identifier
`agents[].tokens`	number	Tokens consumed by this agent
`agents[].cost`	number	Total cost attributed to this agent
`agents[].calls`	number	Number of AI calls made by this agent
`agents[].avgCostPerCall`	number	Average cost per call for this agent
`agents[].model`	string	Model or plan tier used
`daily`	array	Daily cost breakdown
`daily[].date`	string	Date label (for example `Mar 29`)
`daily[].cost`	number	Cost for this day
`daily[].tokens`	number	Tokens used on this day
`modelBreakdown`	array	Cost breakdown by model
`modelBreakdown[].model`	string	Model identifier
`modelBreakdown[].percent`	number	Percentage of total cost
`modelBreakdown[].cost`	number	Cost attributed to this model
`isMockData`	boolean	Always `false`. Indicates that the response uses real data.
`plan`	string	User’s current plan
`planMonthlyCost`	number	Monthly cost of the subscription plan in USD
`agentCount`	number	Total number of agents
`activeAgents`	number	Number 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

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

Monthly token quotas

Plan	Monthly token quota
`solo` / `underground` / `starter`	2,000,000
`collective` / `pro`	6,000,000
`label` / `scale`	20,000,000
`network` / `enterprise`	Unlimited

These quotas were updated in April 2026. When a user exceeds their monthly quota, chat completion requests return a 429 status with the QUOTA_EXCEEDED error code. See Token quotas for details on enforcement behavior.

Errors

Code	Description
401	Unauthorized — no valid session
500	Failed 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
  }
}

Field	Type	Description
`agents.active`	number	Number of agents with status `active`
`agents.total`	number	Total number of agents
`agents.limit`	number	Maximum agents allowed by the user’s plan
`agents.newToday`	number	Agents created today
`skills.installed`	number	Total installed skills across all agents
`tasks.total`	number	Total scheduled tasks across all agents

Plan agent limits

Plan	Agent limit
`free` / `solo` / `starter`	1
`pro` / `collective`	3
`scale` / `label`	10
`enterprise` / `network`	100

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 }
}

Code	Description
401	Unauthorized — no valid session, or user not found (returns `404`)

Getting Started

Core Concepts

Integrations

Core Services

Payments

API Reference

MCP

Security

Dashboard API

Dashboard API

Dashboard data

Response

Errors

Dashboard analytics

Query parameters

Response

Errors

Dashboard bootstrap

Response

Errors

Dashboard cost

Query parameters

Response

Plan pricing

Monthly token quotas

Errors

Dashboard stats

Response

Plan agent limits

Errors

Getting Started

Core Concepts

Integrations

Core Services

Payments

API Reference

MCP

Security

Documentation Index

​Dashboard API

​Dashboard data

​Response

​Errors

​Dashboard analytics

​Query parameters

​Response

​Errors

​Dashboard bootstrap

​Response

​Errors

​Dashboard cost

​Query parameters

​Response

​Plan pricing

​Monthly token quotas

​Errors

​Dashboard stats

​Response

​Plan agent limits

​Errors

Dashboard API

Dashboard data

Response

Errors

Dashboard analytics

Query parameters

Response

Errors

Dashboard bootstrap

Response

Errors

Dashboard cost

Query parameters

Response

Plan pricing

Monthly token quotas

Errors

Dashboard stats

Response

Plan agent limits

Errors