Paid (LLM) endpoints

LLM · paid plans

Scopes:

• charts:read — GET /v1/geolocation/places, GET /v1/llm/interpretations, GET /v1/llm/interpretations/{id}, GET /v1/llm/usage-summary, POST /v1/llm/chart-reading, POST /v1/llm/dasha-forecast, POST /v1/llm/muhurta-reasoning, POST /v1/llm/theme/{theme}
• interpretations:write — POST /v1/interpretations, POST /v1/interpretations/natal
• no scope — GET /v1/plans

Paid plans only

These endpoints write text with a large language model, which costs money per call. They are not included in the Free plan: on Free they answer 403 plan_feature_unavailable before any model is called, so nothing is charged and nothing is sent to a model provider. Paid plans (Hobby, Pro) are coming soon — see GET /v1/plans.

Every other endpoint of the API is pure computation and is included in every plan.

Which endpoints use an LLM

Endpoint	When the model is called	Page
POST /v1/llm/theme/{theme} (+ /stream)	always, unless a cached copy is returned	LLM interpretations
POST /v1/llm/chart-reading (+ /stream)	always, unless cached	LLM interpretations
POST /v1/llm/dasha-forecast (+ /stream)	always, unless cached	LLM interpretations
POST /v1/llm/muhurta-reasoning (+ /stream)	always, unless cached	LLM interpretations
POST /v1/interpretations/natal, /relationship, /forecast	always, unless cached	Interpretations
POST /v1/interpretations	only with use_llm_rewrite: true (the template version is free)	Interpretations
GET /v1/geolocation/places	paid plans: the model helps read free-text place names; Free: place database only, still works	Geolocation

Reading what was already generated is free on every plan: GET /v1/llm/interpretations, GET /v1/llm/interpretations/{id}, GET /v1/llm/usage-summary.

Responses you can get

Status	error.code	Meaning	What to do
403	plan_feature_unavailable	Your plan has no LLM access	Use the template endpoints, or upgrade when paid plans open
429	llm_budget_exceeded	Paid plan: the hourly LLM spend cap is used up (details.cap_usd, details.spent_usd)	Wait for the rolling hour
429	llm_tier_rate_limited	Too many requests for this quality tier	Respect Retry-After
503	llm_all_providers_failed, llm_timeout, llm_unavailable	The model provider is down	Retry later

Streaming (/stream) routes check plan and budget before the stream starts, so these errors arrive as normal HTTP statuses, not inside an event stream.

{
    "error": {
        "code": "plan_feature_unavailable",
        "message_key": "errors.llm.not_in_plan",
        "message": "This endpoint uses an LLM, which is not included in your plan. Paid plans with LLM access are coming soon; see GET /v1/plans.",
        "details": { "plan": "free", "feature": "llm" },
        "request_id": "019e…"
    }
}

What is sent to the model

Only the birth moment (UTC) and computed planet positions — never names, coordinates or account data. Calls go through OpenRouter to the model provider chosen for the quality tier. See Sub-processors and Data & privacy for developers.