GET · HOROSCOPE

Monthly Horoscope

Endpoint GET https://starsapi.com/api/v3/horoscope/monthly

Returns the calendar-month horoscope (1st through last day, IST) for a single zodiac sign. Returns ~1000 words of content organized into 6 H2 sections — Overview, Career & Business, Money & Finance, Love & Relationships, Health & Wellbeing, and Important Dates — plus a structured content_sections field for app tabs and notifications.

Note: monthly uses month=, not date=. Daily and weekly endpoints accept date= for picking the time window. The monthly endpoint accepts month= instead. The values it accepts are different too — see the month formats section below.

Authentication

Required. Three methods accepted:

Method	Example
Header (recommended)	`X-Api-Key: am_live_xxxxxxxxxxxx`
Bearer	`Authorization: Bearer am_live_xxxxxxxxxxxx`
Query	`?api_key=am_live_xxxxxxxxxxxx`

See authentication for security considerations.

Query parameters

Param	Required	Default	Accepted values
`sign`	Yes	—	`Aries`, `Taurus`, `Gemini`, `Cancer`, `Leo`, `Virgo`, `Libra`, `Scorpio`, `Sagittarius`, `Capricorn`, `Aquarius`, `Pisces`
`zodiac_system`	No	`vedic_moon`	`vedic_moon` · `western_sun`
`month`	No	`this-month`	See the month formats section below
`language`	No	`en`	`en` · `hi`

No sub_type parameter. Daily and weekly accept sub_type=love / career to focus a short forecast on one area. Monthly doesn't need this — Love and Career already have their own H2 sections inside every forecast. Always returns content equivalent to sub_type=general.

Month formats

The month parameter accepts several formats:

Format	Example	Resolves to
Keyword	`this-month`	1st through last day of current calendar month (IST)
Keyword	`next-month`	1st through last day of upcoming month
Keyword	`last-month`	1st through last day of previous month
Calendar month	`2026-06`	June 1 – June 30, 2026
Any date in month	`2026-06-15`	June 1 – June 30 (system resolves to the month containing the date)

Response shape

Successful responses contain a top-level status + success flag, a data object, and a meta envelope:

Field	Type	Description
`status`	integer	HTTP status code echo (200 on success).
`success`	boolean	Always `true` on success.
data
`data.sign`	string	Echo of the requested sign.
`data.zodiac_system`	string	Zodiac system used.
`data.sub_type`	string	Always `general` for monthly.
`data.period_type`	string	Always `monthly` for this endpoint.
`data.period_key`	string	Calendar month key, e.g. `2026-06`. Stable cache key.
`data.period_start`	string (YYYY-MM-DD)	First day of the target month.
`data.period_end`	string (YYYY-MM-DD)	Last day of the target month.
`data.language`	string	Language of the returned content.
`data.summary`	string	One-line summary — ideal for push notifications, subject lines, list previews.
`data.content`	string (HTML)	Full content with `<h2>` section headings, `<p>` paragraphs, `<ul>`/`<li>` for dates.
`data.content_text`	string	Plain text with section labels as headings, paragraphs separated by `\n\n`.
`data.content_paragraphs`	array of strings	Each paragraph (and section title) as a separate string.
`data.content_sections`	object	Monthly only. Structured sections object — see below.
`data.mood`	string	Mood keyword for the month (e.g. `Nurturing`, `Transformative`).
`data.key_theme`	string	One-phrase theme for the month.
`data.lucky_number`	integer	Suggested lucky number for the month.
`data.lucky_color`	string	Suggested lucky color.
`data.compatible_sign`	string	Most compatible sign for the month.
`data.ratings.love`	integer (1–5)	Love rating for the month.
`data.ratings.career`	integer (1–5)	Career rating.
`data.ratings.money`	integer (1–5)	Money rating.
`data.ratings.health`	integer (1–5)	Health rating.
`data.ratings.overall`	integer (1–5)	Overall rating.
`data.dos`	array of strings	Recommended actions for the month.
`data.donts`	array of strings	Actions to avoid for the month.
`data.generated_at`	string	When this content was generated (server time).
`data.served_tier`	string	Content tier served (e.g. `canonical`, `premium`).
`data.partner_tier`	string	Your partner tier as configured on the API key.
meta
`meta.endpoint`	string	Echo of the called endpoint path.
`meta.version`	string	API version (currently `3.0`).
`meta.response_time_ms`	integer	Server-side response time in milliseconds.
`meta.timestamp`	string (ISO 8601)	UTC time the response was served.
`meta.credits_remaining`	integer	API credits remaining on your plan.
`meta.request_id`	string	Unique request identifier — include in support tickets.

Note that monthly does not include a lucky_time field (unlike daily, which returns a time window).

The `content_sections` object (monthly-only)

In addition to the three content formats shared with daily and weekly (content, content_text, content_paragraphs), monthly returns a fourth format: a structured content_sections object with each section as its own keyed entry. Perfect for tabbed UIs, section-specific notifications, and calendar imports.

Section key	Returns
`overview`	`{title, body, body_html}` — synthesis of the month's defining theme
`career`	`{title, body, body_html}` — Mercury / Sun / Saturn transits applied to work and profession
`money`	`{title, body, body_html}` — income, investments, expenses (Vedic: 2nd/11th/8th bhava framework)
`love`	`{title, body, body_html}` — Venus / Mars / Moon transits for partnerships
`health`	`{title, body, body_html}` — physical and mental health
`important_dates`	Array of `{date_label, event}` — major astrological dates with significance

Section sub-object shape

Field	Type	Description
`title`	string	English section title (e.g. `"Career & Business"`). Stable across languages.
`body`	string	Plain text body of the section.
`body_html`	string	HTML-wrapped body (e.g. `<p>...</p>`).

Important dates entry shape

Field	Type	Description
`date_label`	string	Human-friendly date label (e.g. `"Tuesday, June 2"`).
`event`	string	Description of the astrological event (e.g. `"Jupiter enters Cancer"`).

Important-dates entries are typically ordered by astrological importance, not chronologically. Headline events (eclipses, slow planet ingresses, retrograde stations) come first; smaller events follow. Sort the array client-side by parsing date_label if you need calendar order.

The four content formats

Same horoscope, four pre-formatted variants — the same three as daily/weekly, plus the monthly-only structured sections.

Field	Format	Use for
`content`	HTML (with `<h2>` sections)	Web pages, Flutter `Html` widget, WordPress, email bodies. H2s give natural SEO structure.
`content_text`	Plain text	SMS, WhatsApp/Telegram bots, voice TTS. Section labels appear as plain headings.
`content_paragraphs`	Array of strings	Custom UI — each paragraph as a swipeable card. Section titles are array items too.
`content_sections`	Object (monthly only)	Tabbed UIs, section-specific push, calendar imports. Each section has its own keyed entry.

Use cases

Tabbed monthly screen — use content_sections with 6 tabs (Overview / Career / Money / Love / Health / Important Dates). Each section pre-formatted as body_html.
Calendar integration — iterate content_sections.important_dates as calendar event source. Each entry is ready to import into Google/Apple Calendar.
Section-specific push — send content_sections.career.body Monday morning, love.body Friday evening. One forecast, many touchpoints.
Monthly newsletter — use full content (HTML with H2s) as email body. summary as subject line.
Blog / WordPress post — drop content into post body. H2 sections give natural SEO heading hierarchy.
WhatsApp / Telegram bot — reply to "show me my career outlook" with content_sections.career.body only.
Monthly dashboard — ratings for 5-star bars, lucky_* as highlight tiles, mood as emoji.

Fetching all 12 signs at once

For monthly sign-picker screens or full-zodiac dashboards, fetch all 12 signs in parallel. Each call counts as one request against your quota.

// JavaScript
const signs = ['Aries','Taurus','Gemini','Cancer','Leo','Virgo',
               'Libra','Scorpio','Sagittarius','Capricorn','Aquarius','Pisces'];

const all = await Promise.all(
  signs.map(s => fetch(
    `https://starsapi.com/api/v3/horoscope/monthly?sign=${s}&month=this-month`,
    { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
  ).then(r => r.json()))
);

// Use all[i].data.content_sections.overview.body for sign-picker cards

Cache for 30 days. Monthly horoscopes don't change once generated. Use data.period_key (e.g. 2026-06) as your cache key — rotates automatically when the month changes. Fetch once on first app open of the month, cache until next month start.

Errors

HTTP	Code	Cause
400	`MISSING_SIGN`	`sign` param not provided
400	`INVALID_SIGN`	Sign name not in 12-sign list
400	`INVALID_ZODIAC_SYSTEM`	Must be `vedic_moon` or `western_sun`
400	`INVALID_LANGUAGE`	Unsupported language code
400	`INVALID_MONTH`	Bad month format. Use `this-month`, `next-month`, `last-month`, `YYYY-MM`, or `YYYY-MM-DD`
401	`AUTH_MISSING_KEY`	No API key in request
401	`AUTH_INVALID_KEY`	Key format invalid or not found
401	`AUTH_REVOKED_KEY`	Key has been revoked
403	`AUTH_ORIGIN_DENIED`	Request from non-whitelisted origin
404	`HOROSCOPE_NOT_AVAILABLE`	Content not yet generated for that month (querying a future month before its cron runs)
429	`RATE_LIMIT_EXCEEDED`	Plan quota exceeded

Error response format

{
  "status": 404,
  "success": false,
  "error": {
    "code": "HOROSCOPE_NOT_AVAILABLE",
    "message": "Horoscope not yet generated for Aries vedic_moon/general/en in 2026-05"
  },
  "meta": {
    "endpoint": "/api/v3/horoscope/monthly",
    "version": "3.0",
    "response_time_ms": 1,
    "timestamp": "2026-05-31T14:10:17+05:30",
    "request_id": "b32a8a86bb97200f"
  }
}

const response = await fetch(
  'https://starsapi.com/api/v3/horoscope/monthly?sign=Cancer&month=2026-06',
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
);
const result = await response.json();

if (result.success) {
  console.log(result.data.summary);
  console.log(result.data.content);          // HTML
  console.log(result.data.lucky_number);
}

import requests
import os

response = requests.get(
    'https://starsapi.com/api/v3/horoscope/monthly',
    headers={'X-Api-Key': os.environ['STARSAPI_KEY']},
    params={'sign': 'Cancer', 'month': '2026-06'}
)
result = response.json()

if result['success']:
    print(result['data']['summary'])
    print(result['data']['content_text'])
    print(f"Lucky: {result['data']['lucky_number']}")

<?php
$ch = curl_init('https://starsapi.com/api/v3/horoscope/monthly?sign=Cancer&month=2026-06');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Api-Key: ' . getenv('STARSAPI_KEY')
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

if ($data['success']) {
    echo $data['data']['summary'];
    echo $data['data']['content'];          // HTML
    echo "Lucky number: " . $data['data']['lucky_number'];
}

import 'package:http/http.dart' as http;
import 'dart:convert';

Future<Map<String, dynamic>> getHoroscope() async {
  final response = await http.get(
    Uri.parse('https://starsapi.com/api/v3/horoscope/monthly?sign=Cancer&month=2026-06'),
    headers: {'X-Api-Key': 'YOUR_API_KEY'},
  );
  return jsonDecode(response.body);
}

// Use in a widget:
//   final result = await getHoroscope();
//   final summary = result['data']['summary'];
//   final content = result['data']['content'];   // HTML for flutter_html
//   final mood    = result['data']['mood'];

import Foundation

func getHoroscope() async throws -> [String: Any] {
    var request = URLRequest(url: URL(string:
        "https://starsapi.com/api/v3/horoscope/monthly?sign=Cancer&month=2026-06"
    )!)
    request.setValue("YOUR_API_KEY", forHTTPHeaderField: "X-Api-Key")

    let (data, _) = try await URLSession.shared.data(for: request)
    let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]
    return json
}

import okhttp3.*
import org.json.JSONObject

val client = OkHttpClient()

fun getHoroscope(callback: (JSONObject) -> Unit) {
    val request = Request.Builder()
        .url("https://starsapi.com/api/v3/horoscope/monthly?sign=Cancer&month=2026-06")
        .addHeader("X-Api-Key", "YOUR_API_KEY")
        .build()

    client.newCall(request).enqueue(object : Callback {
        override fun onResponse(call: Call, response: Response) {
            callback(JSONObject(response.body!!.string()))
        }
        override fun onFailure(call: Call, e: java.io.IOException) {
            e.printStackTrace()
        }
    })
}

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET",
        "https://starsapi.com/api/v3/horoscope/monthly?sign=Cancer&month=2026-06", nil)
    req.Header.Set("X-Api-Key", os.Getenv("STARSAPI_KEY"))

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    data := result["data"].(map[string]interface{})
    fmt.Println(data["summary"])
}

require 'net/http'
require 'json'

uri = URI('https://starsapi.com/api/v3/horoscope/monthly?sign=Cancer&month=2026-06')
req = Net::HTTP::Get.new(uri)
req['X-Api-Key'] = ENV['STARSAPI_KEY']

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
res = http.request(req)

data = JSON.parse(res.body)

if data['success']
  puts data['data']['summary']
  puts data['data']['content_text']
  puts "Lucky: #{data['data']['lucky_number']}"
end

200 RESPONSE

{
  "status": 200,
  "success": true,
  "data": {
    "sign": "Cancer",
    "zodiac_system": "vedic_moon",
    "sub_type": "general",
    "period_type": "monthly",
    "period_key": "2026-06",
    "period_start": "2026-06-01",
    "period_end": "2026-06-30",
    "language": "en",

    "summary": "June brings transformative energy as Jupiter, Venus, and Mercury transit your 1st bhava...",

    "content": "<h2>Monthly Overview</h2><p>June unfolds...</p><h2>Career &amp; Business</h2><p>...</p>",
    "content_text": "Monthly Overview\n\nJune unfolds...\n\nCareer & Business\n\n...",
    "content_paragraphs": ["Monthly Overview", "June unfolds...", "Career & Business", "..."],

    "content_sections": {
      "overview": {
        "title": "Monthly Overview",
        "body": "June unfolds with an important milestone...",
        "body_html": "<p>June unfolds...</p>"
      },
      "career": {
        "title": "Career & Business",
        "body": "The transits of Jupiter and Venus...",
        "body_html": "<p>The transits...</p>"
      },
      "money":  { "title": "Money & Finance",      "body": "...", "body_html": "<p>...</p>" },
      "love":   { "title": "Love & Relationships", "body": "...", "body_html": "<p>...</p>" },
      "health": { "title": "Health & Wellbeing",   "body": "...", "body_html": "<p>...</p>" },
      "important_dates": [
        { "date_label": "Tuesday, June 2",  "event": "Jupiter enters Cancer" },
        { "date_label": "Monday, June 8",   "event": "Venus enters Cancer" },
        { "date_label": "Monday, June 15",  "event": "New Moon in Taurus" },
        { "date_label": "Monday, June 22",  "event": "Mercury enters Cancer" },
        { "date_label": "Monday, June 29",  "event": "Mercury stations retrograde" },
        { "date_label": "Tuesday, June 30", "event": "Full Moon in Sagittarius" }
      ]
    },

    "mood": "Nurturing",
    "key_theme": "Emotional nurturing and personal growth",
    "lucky_number": 7,
    "lucky_color": "blue",
    "compatible_sign": "Taurus",

    "ratings": {
      "love": 5, "career": 4, "money": 4,
      "health": 4, "overall": 4
    },

    "dos": [
      "Embrace family gatherings and nurturing conversations",
      "Revise your financial plans for better clarity",
      "Engage in self-care practices during the full moon"
    ],
    "donts": [
      "Sign new contracts during Mercury retrograde",
      "Neglect emotional needs in relationships",
      "Make impulsive financial decisions"
    ],

    "generated_at": "2026-05-21 15:17:27",

    "served_tier": "canonical",
    "partner_tier": "canonical"
  },
  "meta": {
    "endpoint": "/api/v3/horoscope/monthly",
    "version": "3.0",
    "response_time_ms": 8,
    "timestamp": "2026-05-31T14:10:17+05:30",
    "credits_remaining": 199475,
    "request_id": "bfd1c53fb788056e"
  }
}