Get Dashboard Revenue (v1)

Get detailed revenue, expenses, and net income data with time-series breakdown for a specific period (today, week, month, or custom date range).

Method & Path

GET /v1/admin/dashboard/revenue

Description

Retrieves time-series revenue data including:

• Revenue (payments) breakdown by time buckets
• Expenses breakdown by time buckets
• Net income (revenue - expenses) for each time bucket
• Summary totals for the selected period

Data Granularity:

• today: Hourly breakdown (24 data points from start of day to current hour)
• week: Daily breakdown (last 7 days)
• month: Daily breakdown (each day of current month)
• custom: Daily breakdown for the specified date range (requires startDate and endDate parameters)

All metrics are calculated in real-time from the database.

Authentication

Required: Admin authentication with dashboard.view permission.

Include the admin JWT token in the Authorization header:

Authorization: Bearer <admin_token>

Headers

Authorization: Bearer <admin_token>
Content-Type: application/json

Query Parameters

Parameter	Type	Required	Description
period	string	Yes	Time period for data aggregation. Must be one of: today, week, month, custom
startDate	string	Conditional	Start date for custom period (required when period=custom). Format: YYYY-MM-DD
endDate	string	Conditional	End date for custom period (required when period=custom). Format: YYYY-MM-DD

Request Body

None.

Response 200 OK

{
  "data": [
    {
      "date": "2024-01-15-14",
      "revenue": 1250.50,
      "expenses": 320.00,
      "net": 930.50
    },
    {
      "date": "2024-01-15-15",
      "revenue": 890.25,
      "expenses": 150.00,
      "net": 740.25
    }
  ],
  "summary": {
    "revenue": 15200.75,
    "expenses": 4850.00,
    "net": 10350.75
  },
  "period": "today"
}

Response Fields

data

Array of time-series data points. Each point contains:

• date (string): Date/time identifier for the data point
  • For today: Format is YYYY-MM-DD-HH (e.g., "2024-01-15-14" for 2 PM)
  • For week, month, and custom: Format is YYYY-MM-DD (e.g., "2024-01-15")
• revenue (number): Total revenue (payments) for this time bucket (USD)
• expenses (number): Total expenses for this time bucket (USD)
• net (number): Net income (revenue - expenses) for this time bucket (USD)

summary

Summary totals for the entire selected period:

• revenue (number): Total revenue for the period (USD)
• expenses (number): Total expenses for the period (USD)
• net (number): Total net income for the period (USD)

period

The period parameter that was used for this request (today, week, month, or custom).

Examples

Request: Today's Revenue (Hourly)

GET /v1/admin/dashboard/revenue?period=today

Response:

{
  "data": [
    {
      "date": "2024-01-15-00",
      "revenue": 0,
      "expenses": 0,
      "net": 0
    },
    {
      "date": "2024-01-15-01",
      "revenue": 150.00,
      "expenses": 50.00,
      "net": 100.00
    },
    ...
  ],
  "summary": {
    "revenue": 1250.50,
    "expenses": 320.00,
    "net": 930.50
  },
  "period": "today"
}

Request: Last Week's Revenue (Daily)

GET /v1/admin/dashboard/revenue?period=week

Response:

{
  "data": [
    {
      "date": "2024-01-09",
      "revenue": 2150.00,
      "expenses": 850.00,
      "net": 1300.00
    },
    {
      "date": "2024-01-10",
      "revenue": 1890.50,
      "expenses": 720.00,
      "net": 1170.50
    },
    ...
  ],
  "summary": {
    "revenue": 15200.75,
    "expenses": 4850.00,
    "net": 10350.75
  },
  "period": "week"
}

Request: Current Month's Revenue (Daily)

GET /v1/admin/dashboard/revenue?period=month

Response:

{
  "data": [
    {
      "date": "2024-01-01",
      "revenue": 3200.00,
      "expenses": 1200.00,
      "net": 2000.00
    },
    {
      "date": "2024-01-02",
      "revenue": 2850.50,
      "expenses": 950.00,
      "net": 1900.50
    },
    ...
  ],
  "summary": {
    "revenue": 98750.25,
    "expenses": 32500.00,
    "net": 66250.25
  },
  "period": "month"
}

Request: Custom Date Range Revenue (Daily)

GET /v1/admin/dashboard/revenue?period=custom&startDate=2024-01-01&endDate=2024-01-15

Response:

{
  "data": [
    {
      "date": "2024-01-01",
      "revenue": 3200.00,
      "expenses": 1200.00,
      "net": 2000.00
    },
    {
      "date": "2024-01-02",
      "revenue": 2850.50,
      "expenses": 950.00,
      "net": 1900.50
    },
    ...
    {
      "date": "2024-01-15",
      "revenue": 2100.00,
      "expenses": 800.00,
      "net": 1300.00
    }
  ],
  "summary": {
    "revenue": 45200.75,
    "expenses": 15200.00,
    "net": 30000.75
  },
  "period": "custom"
}

Common Errors

• 400 Bad Request:
  • Invalid period parameter. Must be one of: today, week, month, custom
  • Missing startDate or endDate when period=custom
  • Invalid startDate or endDate format. Use YYYY-MM-DD format
  • startDate is after endDate
• 401 Unauthorized: Missing or invalid admin authentication token
• 403 Forbidden: Insufficient permissions (missing dashboard.view permission)
• 500 Internal Server Error: Server error during data aggregation

Notes

• All date-based calculations use UTC timezone
• Revenue includes all payment types (subscription, ai-tools, sms, storage)
• For today period, data points are generated for each hour from 00:00 to the current hour
• For week period, includes the last 7 days (including today)
• For month period, includes all days from the 1st of the current month to today
• For custom period, includes all days from startDate to endDate (inclusive). Both dates must be in YYYY-MM-DD format
• When using custom period, startDate must be before or equal to endDate
• Empty time buckets (with no payments or expenses) will have zero values but still appear in the response
• All amounts are in USD