How does /horary/ask work?

You POST a question string and the querent's location + timestamp. The API runs four stages: an AI classifier picks the category and subcategory, the judgment engine casts the chart and runs the full traditional rule set, the AI summarizer writes a plain-language answer, and the response comes back with a confidence_band. Under 2 seconds end-to-end.

What's the difference between /horary/ask and /horary/chart?

/horary/chart is the lower-level endpoint. You give it the question category yourself, and it returns the raw Judgment object with no summary. /horary/ask is the new flagship: it accepts a plain-language question, classifies it for you, judges it, and returns a written summary in the language you ask for. Use /horary/ask when you want to ship a question box. Use /horary/chart when you already know the category and want raw data.

Can I get answers in languages other than English?

Yes. The summarizer ships in five languages: en, ru, de, fr, es. Pass the target language in the request and the summary comes back in that language with language-specific phrasing rules. Every language uses the same judgment pipeline underneath, so the verdict is identical; only the written summary changes.

How does the API handle Void of Course Moon in Lilly exception signs?

The MoonCalculator honors Lilly's exception signs: Taurus, Cancer, Sagittarius, and Pisces. In those signs a VOC Moon is mitigated rather than negated. The response exposes voc_exception_sign and voc_effective_strength so the judgment engine downgrades the verdict instead of vetoing it, and the RadicalityChecker cites the exception sign by name in its flag description.

Is the question cached?

Yes, at the classifier level. The classifier result is keyed by a sha256 hash of the normalized question and stored in Redis with a 7-day TTL. The second identical question costs zero LLM tokens for classification. The judgment stage runs fresh every time because the chart depends on the timestamp.

How does the summarizer avoid sounding like a fortune teller?

The prompt template forbids prescriptive verbs. Phrases like "you must," "you should," or "don't do X" are blocked. The summarizer reports what the chart says, not what the user should do. It also elevates radicality flags into the visible answer when confidence_band is medium or low, so caveats arrive before the verdict.

What happens when both translation_of_light and frustration are active?

Frustration wins. The summarizer prompt has an explicit rule: when frustration is present, suppress the translation_of_light callout in the written summary. Both flags remain in the raw Judgment object, but the user-facing text avoids the contradiction of "a third party brings it together, but it falls apart at the last moment."

What are the 14 horary question categories?

Health, Money, Communication, Property, Children/Pregnancy, Employment, Relationship, Legal matters, Danger, Travel, Lost items, Career, Wishes, and Secrets. Each maps to specific houses and judgment rules from Lilly and Bonatti. The marriage category has two subcategories (marriage and marriage.reconciliation), and the 7th-house family also includes business_partnership.

How fast is end-to-end latency?

Under 2 seconds for the full /horary/ask pipeline: classify, judge, summarize. The classifier cache cuts that further on repeat questions because the Redis lookup replaces an LLM call. The judgment stage itself is sub-500ms; the LLM stages are what the 2-second budget mostly covers.

Can I use the API without the AI layer?

Yes. /horary/chart returns the raw Judgment object without invoking the summarizer. You pass the category explicitly and skip the classifier. Use this when you want to render your own UI from structured data, or when you have your own copy and don't need the AI summary.

How much does the horary astrology API cost?

Horary endpoints are a premium feature available starting from the Ultra plan. AI classification and summarization are included, with no separate LLM bill on your side.

Do you support traditional horary house systems?

Regiomontanus is the default, the system Lilly and Bonatti actually used. Most general-purpose astrology APIs default to Placidus, which is wrong for horary. You can override the house system if you have a reason, but the default is the traditional choice.

What is radicality and what flags does the API emit?

Radicality is the traditional check on whether a chart is fit to judge. The RadicalityChecker emits a typed RadicalityFlag list covering early/late ascendant, Saturn in the 7th, VOC Moon (with exception-sign handling), malefics afflicting significators, and the rest of the classical battery. Render the flags directly in your UI; no free-text parsing required.

What is extended lunar sequence analysis?

The Moon is the primary timer in horary, so the API tracks every aspect it will make up to 45° ahead, not just the next one. This Frawley/Barclay-style chain-of-events view reveals the intervening aspects that shape timing. Instead of "something happens in 3 weeks," you get the sequence: interview in 1 week (Moon-Mercury), delay (Moon-Saturn), offer (Moon-Jupiter) at 3 weeks.

What are the four Secondary Perfection mechanisms?

Translation of Light (a faster planet carries light between significators), Collection of Light (a slower planet receives aspects from both and brings them together), Prohibition (a malefic completes its aspect first and blocks the matter), and Frustration (a significator goes retrograde or changes sign before perfection). The API analyzes all four on every chart and reports which are active.

How does the API handle marriage.reconciliation?

Reconciliation questions ("will my husband and I get back together") share the 7th house with fresh marriage questions but need a different judgment lens. The classifier routes these to the marriage.reconciliation subcategory automatically. The judgment engine weighs separating vs. applying aspects differently and gives more weight to translation/collection involving the Moon as the natural significator of past matters.

Can horary astrology predict pregnancy and fertility?

Yes. The fertility category uses 5th-house analysis with the Bonatti fruitful-sign overlay and the Arabic Parts of Children and Pregnancy. The classifier routes pregnancy questions correctly, and the dedicated /horary/fertility endpoint exists for apps that want to skip the classifier and go straight to fertility-specific judgment rules.

How do I integrate /horary/ask in my app?

Wire a question box to a POST request. Send the question string, the querent's timestamp, the querent's location, and the desired output language. Render the returned summary and the confidence_band. Optionally surface the radicality_flags list as a "caveats" section. Integration is typically under an hour because there's no client-side rule logic to write.

What's the difference between horary and natal astrology?

Natal astrology reads a birth chart to describe personality and life patterns. Horary reads a chart cast for the moment a question is asked to answer that specific question. Natal answers "who am I." Horary answers "what should I do about X right now." Different charts, different rules, different use cases.

AI-Powered Horary Judgment

Ask a Question in Plain Language. Get an AI-Judged Horary Answer

POST a question to /horary/ask.

The API classifies it, runs the full traditional analysis, and returns a plain-language answer with a confidence band. Under 2 seconds end-to-end.

View Demo

<2s

Ask → Answer

AI-Powered

Classify + Summarize

Output Languages

High / Med / Low

Confidence Bands

Used by 2,800+ developers and astrologers

William Lilly + Bonatti methodology

Swiss Ephemeris precision

Premium Feature

Horary Astrology is a premium feature available starting from the Ultra plan.

You have to hand-code 1000+ years of judgment rules: radicality, void-of-course Moon, essential and accidental dignities, reception, perfection, translation and collection of light, prohibition, frustration
You need to parse free-text questions and route them to the right house and significator scheme. Marriage goes to the 7th, fertility to the 5th, litigation to the 7th, lost objects to the 2nd
You have to disambiguate "will I marry her" from "will we get back together." Same house, different sub-rules
You need a sane way to express uncertainty when the chart says "yes, but barely"
And you have to do all of this in five languages without inventing a translation pipeline

Ship horary with

POST a plain-language question to /horary/ask. The AI classifier picks the category and subcategory from 10 few-shot examples per language
The judgment engine runs the full traditional rule set: radicality flags, VOC handling, dignities, perfection, translation/collection of light, prohibition, frustration
The AI summarizer converts the technical verdict into a plain answer in en, ru, de, fr, or es, with a confidence_band of high, medium, or low
Marriage vs. business partnership, marriage vs. reconciliation: the classifier handles the edge cases that break naive keyword routing
Redis caches classifications for 7 days, so repeat questions skip the LLM round trip

Production Metrics

Real numbers from the new /horary/ask pipeline

<2s

End-to-End (classify + judge + summarize)

en / ru / de / fr / es

Summary Languages

7-day TTL

Classifier Cache (Redis)

confidence_band

Returned Per Answer

What Ships in the New Horary Pipeline

AI classification, AI summary, typed flags, multilingual output

/horary/ask Endpoint

POST a plain-language question. Get classification, judgment, and a summary back in one response.

AI Question Classifier

10 few-shot examples per language. Handles marriage vs. business partnership and marriage vs. reconciliation.

AI Summarizer

Turns the technical Judgment object into a 2–4 sentence plain answer. No prescriptive verbs.

Confidence Band

Every answer returns high / medium / low. Drive UI hedging directly from the field.

Typed Radicality Flags

RadicalityChecker emits a structured flag list. Render in the UI without parsing free text.

VOC Exception Signs

Lilly exceptions (Taurus, Cancer, Sagittarius, Pisces) mitigate the VOC verdict instead of vetoing it.

Bonatti VOC Severity

Mild vs. standard severity exposed as a flag for Bonatti-strict audiences.

Turned-Chart Analysis

Optional subject_role parameter routes the question through derived houses via turn_house_cusps.

Marriage Subcategories

Marriage, marriage.reconciliation, and business_partnership get separate judgment lenses.

Multilingual Summaries

en, ru, de, fr, es. Same pipeline, different output language.

Redis Classifier Cache

sha256 question key with a 7-day TTL. Repeat questions skip the LLM round trip.

Perfection Conflict Resolution

When frustration is active, the summary suppresses translation_of_light callouts to avoid contradictory messages.

Extended Lunar Sequence

45° lookahead tracking every Moon aspect for full timing context.

Secondary Perfection

Translation of Light, Collection of Light, Prohibition, and Frustration analyzed on every chart.

Essential & Accidental Dignities

Domicile, exaltation, triplicity, terms, faces + house, aspect, retrograde, combustion.

Regiomontanus Houses

Traditional horary house system as the default, not the Placidus most general-purpose APIs ship.

AI Horary API: How /horary/ask Turns a Plain Question into a Judged Answer

The new flagship endpoint, explained

Horary astrology answers a specific question by casting a chart for the moment the question is asked, then judging the chart against a thousand years of accumulated rules. The hard part for developers has always been the rules themselves: radicality, void-of-course Moon, dignities, reception, the four ways a matter perfects or fails to perfect. The new /horary/ask endpoint hides all of that behind a single POST. You send a question in plain English (or Russian, German, French, Spanish). An AI classifier picks the right category and subcategory using ten few-shot examples per language. The judgment engine runs the full traditional analysis with typed radicality flags and Bonatti-graded void-of-course severity. An AI summarizer turns the technical verdict into a plain answer with a confidence_band of high, medium, or low. The whole pipeline returns in under 2 seconds. Classifier results are cached in Redis for 7 days under a sha256 question key, so repeat questions skip the LLM round trip entirely.

How does the /horary/ask endpoint work, step by step?

Four stages, one HTTP call.

Stage 1: you POST a question string and the querent's location + timestamp.

Stage 2: the AI classifier reads the question and assigns it to one of the traditional categories (marriage, business partnership, fertility, property, litigation, health, lost objects, employment, travel, and the rest), plus a subcategory when relevant (for example marriage.reconciliation for estranged-spouse questions).

Stage 3: the judgment engine casts the chart, identifies significators, runs radicality checks, evaluates dignities, looks for perfection, and emits a typed Judgment object with radicality_flags, voc_treatment, perfection details, and a confidence_band.

Stage 4: the AI summarizer takes the Judgment object and writes a plain-language answer in the requested output language.

The summarizer prompt forbids prescriptive verbs (no "you must do X"), elevates radicality flags as mandatory caveats, and suppresses translation_of_light callouts when frustration is also present in the same chart.

Four stages, one POST, under 2 seconds end-to-end

1 min read

How accurate is the AI classifier and what does it actually do?

The classifier reads the raw question and decides which house and significator scheme the judgment engine should use.

It runs on 10 few-shot examples per supported language (en, ru, de, fr, es) and handles the edge cases that break naive keyword routing.

"Will my business partner buy me out?" goes to business partnership (7th house, but different sub-rules from marriage).

"Will my husband and I get back together?" goes to marriage.reconciliation, not a fresh marriage question.

Same 7th house, different judgment lens.

"Will I get pregnant this year?" goes to fertility (5th house, with the Bonatti fruitful-sign overlay).

The classifier also returns alternatives with confidence scores, so you can show "we read this as a marriage question, was that right?" in your UI.

The result is cached in Redis under a sha256 of the normalized question with a 7-day TTL, so the second identical question costs zero LLM tokens.

10 few-shot examples per language, Redis-cached for 7 days

1 min read

What does confidence_band mean in the response?

Every Judgment object returns a confidence_band field with one of three values.

High means the chart is radical, significators are dignified or well-placed, perfection is clean, and no major radicality flags are active.

You can show the answer to the user without hedging.

Medium means the answer is supported but with caveats: perhaps a moderate VOC mitigation, a separating aspect that still completes, or a Translation of Light doing the work instead of direct perfection.

Low means the chart has serious radicality warnings, the Moon is void without an exception sign, or the judgment depends on contested factors like Bonatti-mild VOC severity.

Use the band to drive UI: high gets a confident headline, medium gets an explainer paragraph, low surfaces the radicality flags and suggests re-asking when the querent has more clarity.

Three bands: high (ship it), medium (caveat), low (re-ask)

1 min read

How does the API handle radicality and Void of Course Moon?

Radicality is the traditional check on whether a chart is fit to judge at all.

The RadicalityChecker emits a typed RadicalityFlag list, so you can render them in the UI without parsing free text.

The list covers early/late ascendant, Saturn in the 7th, Moon void of course, malefics afflicting significators, and the rest of the classical battery.

Void of Course Moon is the tricky one.

The naive rule says "nothing will come of the matter," but Lilly himself listed exception signs (Taurus, Cancer, Sagittarius, Pisces) where a VOC Moon is mitigated, not negated.

The MoonCalculator honors this and emits voc_exception_sign + voc_effective_strength so the judgment engine can downgrade rather than veto.

The RadicalityChecker description cites the exception sign by name.

Bonatti's severity layer (mild vs.

standard) is also exposed as a flag, so apps targeting a Bonatti-strict audience can surface it explicitly.

Typed radicality flags, Lilly exception signs, Bonatti severity grading

1 min read

What are turned charts and when do you need subject_role?

A turned chart re-roots the houses so you can ask about someone other than the querent.

The classic case: the querent is asking about their child's marriage.

The querent's 5th house (children) becomes the radical 1st for the analysis, and every other house turns from there.

The child's 7th (their spouse) is the querent's 11th.

The /horary/ask endpoint accepts an optional subject_role parameter for this.

Set it to "child" and the engine uses the turn_house_cusps utility to derive the right cusps before significator selection.

The same mechanism handles "will my brother's lawsuit succeed" (3rd → 1st) or "will my partner's mother recover" (7th → 4th from radical = 10th).

If you leave subject_role unset, the chart is read radically for the querent.

Optional subject_role parameter for derived-house questions

1 min read

Why a multilingual summarizer matters for horary apps

Horary verdicts are dense.

A raw Judgment object lists significators, aspects, dignities, radicality flags, perfection type, and timing, none of which a paying user wants to parse.

The summarizer takes that object and writes a 2 to 4 sentence plain answer in the user's language.

Five languages ship today: English, Russian, German, French, and Spanish.

Each has its own prompt template with language-specific phrasing rules.

The prompt forbids prescriptive verbs in every language.

The API tells you what the chart says, not what you should do.

It also elevates radicality flags into the visible answer when confidence_band is medium or low, so users see the caveats before the verdict.

When a chart has both translation_of_light and frustration active, the prompt suppresses the translation callout because frustration overrides it, a small detail that prevents contradictory messages in the summary.

5 languages, prompt-enforced caveats, no prescriptive verbs

1 min read

Use Cases

Astrology Apps

Wire /horary/ask to a question box. User types, app returns a confidence-banded answer in their language. Charge $5–15 per reading.

Relationship Platforms

Marriage, reconciliation, and business-partnership classification handle the cases that confuse simple keyword routers.

Career Platforms

Employment, litigation, and property categories cover the high-stakes decisions users actually pay to ask about.

Multilingual Markets

Ship the same endpoint to en, ru, de, fr, and es audiences without building a translation pipeline.

Technical Specifications

Flagship Endpoint	POST /horary/ask: question in, judged answer out
End-to-End Latency	<2s for classify + judge + summarize
Classifier Few-Shot Examples	10 per supported language
Classifier Languages	en, ru, de, fr, es
Summarizer Languages	en, ru, de, fr, es
Classifier Cache	Redis, sha256 question key, 7-day TTL
Confidence Band	Enum: high \| medium \| low
Radicality Flags	Typed RadicalityFlag list (RadicalityChecker)
VOC Exception Signs	Lilly: Taurus, Cancer, Sagittarius, Pisces (mitigated)
VOC Severity	Bonatti mild vs. standard, exposed as flag
VOC Fields	voc_exception_sign, voc_effective_strength, voc_treatment
Marriage Subcategories	marriage, marriage.reconciliation, business_partnership
Turned Charts	Optional subject_role param + turn_house_cusps utility
Summarizer Rules	No prescriptive verbs; radicality flags elevated as caveats
Perfection Suppression	translation_of_light hidden when frustration is also active
Question Categories	14 traditional categories (Lilly/Bonatti)
Ephemeris Source	Swiss Ephemeris
House System	Regiomontanus (traditional horary default)
Lunar Sequence	Extended 45° lookahead with intervening analysis
Secondary Perfection	Translation, Collection, Prohibition, Frustration
Output Format	JSON: classification + judgment + summary

Why /horary/ask Beats Hand-Wired Horary Logic

Feature	Astrology API	Others
Plain-Language Question Input	POST a string, done	You parse and route yourself
Question Classification	AI classifier, 10 few-shot per language	Manual keyword rules
Marriage vs. Business Partnership	Disambiguated automatically	Same 7th house, wrong rules
Marriage vs. Reconciliation	marriage.reconciliation subcategory	Not modeled
Output Summary	AI summarizer in 5 languages	Raw JSON, you write the copy
Confidence Reporting	confidence_band: high / medium / low	Boolean yes/no only
Radicality Flags	Typed flag list	Free-text or absent
VOC Exception Signs	Lilly exceptions mitigate, don't veto	Hard veto
Bonatti VOC Severity	Mild vs. standard, exposed	Not supported
Turned Charts	subject_role param + turn_house_cusps	You compute manually
Classifier Caching	Redis, sha256 key, 7d TTL	None; pay per call
End-to-End Latency	<2s including LLM calls	3–8s or sync-only
Multilingual Summaries	en, ru, de, fr, es	English only
Prescriptive-Verb Guard	Prompt forbids "you must"	No guard
Perfection Conflict Handling	Frustration suppresses translation callout	Both shown, user confused
Lunar Sequence	45° extended lookahead	Next aspect only
Secondary Perfection	All 4 types analyzed	Direct perfection only
House System	Regiomontanus default	Placidus default (wrong for horary)
Price Per Reading	$0.02 via API	$0.10–0.50

Pairs Well With

Cazimi & Combust API

Combust significators are a make-or-break factor in horary judgment. Get the exact orbs and cazimi status.

Electional Astrology API

Once horary says yes, electional picks the optimal moment to act.

Traditional Astrology API

Full dignity tables, sect, antiscia, and the rest of the classical toolkit.

Fertility Astrology API

5th-house specialist for pregnancy and conception questions, with Bonatti fruitful-sign overlay.

Arabic Parts API

97+ Arabic parts including the lots that horary judgment depends on.

Natal Chart API

Generate the querent's natal chart for context alongside the horary verdict.

References & Standards

Swiss Ephemeris (DE431-based) — astronomical calculations source
NASA JPL Planetary Ephemerides — underlying ephemeris dataset
International Astronomical Union (IAU) — body designation and nomenclature standards
IANA Time Zone Database — timezone & DST resolution

Premium Feature

Horary Astrology is a premium feature available starting from the Ultra plan.

Horary Astrology: 2 credits per request

See how many requests you get with each plan

Per-endpoint credit cost

Horary AI Ask (/horary/ask)10 credits per request
Horary Astrology2 credits per request

Simple, Transparent Pricing

Start free, scale as you grow. No hidden fees, no surprises.

Ultra

$37/month

For professional astrology applications

Credit math ↓

All premium endpoints
23 house systems
Advanced AI interpretations
Priority support

High Volume Plans

For enterprise-scale applications

Business

$99/month

For high-volume applications

Credit math ↓

ALL endpoints
White-label ready
Custom AI fine-tuning
Phone support

UNLIMITED

Enterprise

$399+per month

Unlimited requests with dedicated infrastructure

Dedicated server infrastructure
Sub-300ms guaranteed
24/7 dedicated support
99.99% uptime SLA

All plans include comprehensive documentation and SDKs

Questions? Talk to our team

Horary API FAQ

The new /horary/ask pipeline, in detail

Round Out the Traditional Stack

Horary judgment depends on planetary condition, timing, and the wider classical toolkit. Add

cazimi and combust analysis electional astrology timing traditional dignity calculations fertility astrology Arabic parts analysis

Ship a Question Box.

POST a question. Get back a classified, judged, summarized answer with a confidence band, in under 2 seconds, in 5 languages. No rule-engine wiring on your side.

Start Free Now

30-day money-back guarantee

Free migration assistance

No setup fees

Ask a Question in Plain Language. Get an AI-Judged Horary Answer

Building Horary by Hand Is a 1000-Year Rabbit Hole

One Endpoint. The API Handles the Rest.

Production Metrics

What Ships in the New Horary Pipeline

/horary/ask Endpoint

AI Question Classifier

AI Summarizer

Confidence Band

Typed Radicality Flags

VOC Exception Signs

Bonatti VOC Severity

Turned-Chart Analysis

Marriage Subcategories

Multilingual Summaries

Redis Classifier Cache

Perfection Conflict Resolution

Extended Lunar Sequence

Secondary Perfection

Essential & Accidental Dignities

Regiomontanus Houses

AI Horary API: How /horary/ask Turns a Plain Question into a Judged Answer

How does the /horary/ask endpoint work, step by step?

How accurate is the AI classifier and what does it actually do?

What does confidence_band mean in the response?

How does the API handle radicality and Void of Course Moon?

What are turned charts and when do you need subject_role?

Why a multilingual summarizer matters for horary apps

Use Cases

Astrology Apps

Relationship Platforms

Career Platforms

Multilingual Markets

Technical Specifications

Why /horary/ask Beats Hand-Wired Horary Logic

Pairs Well With

Cazimi & Combust API

Electional Astrology API

Traditional Astrology API

Fertility Astrology API

Arabic Parts API

Natal Chart API

References & Standards

Horary Astrology: 2 credits per request

Simple, Transparent Pricing

Ultra

High Volume Plans

Business

Enterprise

Horary API FAQ

How does /horary/ask work?

What's the difference between /horary/ask and /horary/chart?

How accurate is the AI classifier?

What does confidence_band mean in the response?

Can I get answers in languages other than English?

How does the API handle Void of Course Moon in Lilly exception signs?

What is a turned chart and when do I need subject_role?

Does the API consider Bonatti's VOC severity?

Is the question cached?

How does the summarizer avoid sounding like a fortune teller?

What happens when both translation_of_light and frustration are active?

What are the 14 horary question categories?

How fast is end-to-end latency?

Can I use the API without the AI layer?

How much does the horary astrology API cost?

Do you support traditional horary house systems?

What is radicality and what flags does the API emit?

What is extended lunar sequence analysis?

What are the four Secondary Perfection mechanisms?

How does the API handle marriage.reconciliation?

Can horary astrology predict pregnancy and fertility?

How do I integrate /horary/ask in my app?

What's the difference between horary and natal astrology?

Round Out the Traditional Stack

Ship a Question Box.

Building Horary by Hand Is a 1000-Year Rabbit Hole

One Endpoint. The API Handles the Rest.

Production Metrics

What Ships in the New Horary Pipeline

/horary/ask Endpoint