Frequently asked questions

What does one call cost?

One credit per successful call, however much it returns. The exceptions are the PDF report and AI chat endpoints, which cost 25 credits a call. A request for one calculation and a request for forty cost the same, because many endpoints take a `keys` array and every key in one request is covered by that single credit.

Am I charged for failed requests?

No. Occult API never charges for a failed request. The credit is reserved before the calculation runs and released if it does not return cleanly, so a 4xx, a 5xx or a timeout costs nothing and a bad integration cannot drain a balance while it is being debugged. Every response reports what it actually cost in the X-Credits-Charged header.

Do credits expire?

A plan's quota resets every month. Occult API is sold as monthly or yearly plans: each month brings a fresh quota, and calls you did not use in a month do not carry over to the next. Yearly plans work the same way — twelve monthly allowances, billed once.

Is there a free tier?

New accounts receive free credits that are spendable on the live API with a real key, not in a sandbox with its own data. Separately, the playground at occultapi.com/playground makes genuine calls against the running API with your own key, and a failed call there costs nothing.

Is there a subscription?

Yes. Occult API is sold as monthly or yearly plans that renew automatically until you cancel. Cancelling stops the next renewal, and the current period stays usable until it ends. No tier hides an endpoint behind it — every plan can call every endpoint.

I am getting a 402. Is my key wrong?

No. A 402 with the message insufficient_credits means the API key is valid and the quota is used up. Regenerating the key will not help — upgrade the plan or wait for the monthly reset. Only 401 invalid_api_key indicates a problem with the key itself.

Can I use an API key in the browser or a mobile app?

No. An Occult API key is a server-side secret. A key placed in front-end JavaScript or a mobile bundle can be read by anyone who installs the app or opens developer tools, and they can then spend the balance. Call the API from your own server and expose your own endpoint to the client.

I lost my key. Can you send it again?

No, and that is deliberate. Occult API stores keys only as SHA-256 hashes, so neither an administrator nor a database dump can recover one. Create a new key and revoke the old one, which takes effect immediately and does not affect the credit balance.

What happens if a key leaks?

Revoke it from the keys page; revocation is immediate. Every key carries a public eight-character prefix which is indexed precisely so that a key leaked in a public repository can be found and revoked by that prefix alone, without anyone needing the secret half.

Where do the calculations come from?

Occult API computes from NASA JPL ephemeris data — the full data set with 735 fixed stars, covering 500 to 2999 AD. Nothing is read from a pre-computed almanac table; every response is calculated for the exact instant and coordinates in the request.

Your result disagrees with another source. Why?

The usual cause is the ayanamsa. Indian traditions genuinely disagree about it, and a difference of one degree can move a planet across a nakshatra boundary. Occult API exposes 48 ayanamsas and lets each be corrected by degree, minute and second, so the first check is whether both sources are using the same one.

How fast is it?

Median server-side response time is 62 ms, measured across every published example rather than a chosen one. A small number of endpoints are deep scans — a full varshaphal sweep, a year of raasi dasha — and take seconds; those are documented as such in the reference rather than hidden behind the median.

Is there an OpenAPI spec or SDK?

Occult API publishes an OpenAPI 3.1 document at occultapi.com/openapi.json, generated from the same catalogue as the documentation, with an example on every operation — 255 of the 299 captured from a live server, the rest derived from the request schema. It can be used with openapi-generator or any equivalent to produce a typed client in any language. There is also a Postman collection and an MCP server for AI assistants.

Can an AI assistant call it?

Yes. Occult API publishes an MCP server exposing every endpoint through five tools. Searching endpoints and reading request schemas through it costs no credits — only an actual calculation does — so an assistant can explore the whole surface before spending anything. A brief for coding agents is published at occultapi.com/AGENTS.md.

Can I sell what the API returns?

Yes. Occult API grants a royalty-free licence to use the data commercially in your own products, including storing responses in your own database, generating and selling reports, and using it in client work. Attribution is not required. What is not permitted is reselling API access itself as an API.

Do you store the birth data I send?

No. The date, time and place in a request are used to compute the response and are not written to a database afterwards. What is retained per call is the endpoint, timestamp, HTTP status and credits consumed, which is what usage reporting and billing questions require.

Do you offer a DPA?

Yes. Occult API publishes a Data Processing Agreement covering GDPR Article 28, along with a current subprocessor list naming every third party that can access customer data.

If your question is not here, write to mridul.kabra23@gmail.com. For what we have and have not measured, see methodology; for what we store and what we have not built, transparency. Error codes are listed in full under authentication — including why 402 is not an authentication failure.