POST /api/developer/v1/get-energy-metrics

Returns premium astrological energy metrics for a target year. This endpoint requires the premium balance floor before work begins.

Request Body

Field	Type	Required	Description
birthDate	string	Yes	Birth date in YYYY-MM-DD or DD/MM/YYYY format.
birthTime	string	Yes	Birth time in HH:mm 24-hour format.
gender	enum	Yes	Biological gender: "male" or "female".
timezone	string	Yes	IANA timezone such as Asia/Singapore or America/New_York.
targetYear	integer	No	Four-digit calendar year. Defaults to the current year when omitted.

Tier Labels

innateTier and thisYearTier use one of these exact values:

• Extreme Low
• Low-Moderate
• Balanced
• High
• Extreme High

{
  "birthDate": "1995-10-15",
  "birthTime": "08:30",
  "gender": "female",
  "timezone": "Asia/Singapore",
  "targetYear": 2026
}

Response Body

{
  "accessTier": "premium",
  "premiumAvailable": true,
  "result": {
    "targetYear": 2026,
    "metrics": [
      {
        "key": "actionIndex",
        "name": { "en": "Action", "zh": "行动力" },
        "innate": 78,
        "thisYear": 82,
        "variance": 4,
        "innateTier": "High",
        "thisYearTier": "Extreme High"
      }
    ]
  },
  "billing": {
    "premium": true,
    "chargedUsd": 0.04,
    "chargedDisplayUsd": "$0.04",
    "reservedUsd": 0.08,
    "reservedDisplayUsd": "$0.08",
    "remainingBalanceUsd": 12.38,
    "remainingBalanceDisplayUsd": "$12.38",
    "pricingVersion": "developer-v1-2026-06-27"
  }
}

Errors

• 400 for invalid request data with validation issues in details.issues
• 401 for missing or invalid Bearer authentication
• 402 when the account does not meet the premium balance floor before execution begins
• 429 when the API key exceeds 10 calls per second