Frequently asked questions

What does one call cost?

One credit per successful call, whatever the endpoint and however much it returns. 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?

No. Occult API credits are prepaid and do not expire. There is no subscription, no monthly reset and no per-seat charge, so an idle month costs nothing and unused credits stay on the account indefinitely.

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 no account, no card and no key at all.

Is there a subscription?

No. Occult API sells prepaid credit packs rather than monthly plans. You buy credits once and spend them at your own pace, and no tier hides an endpoint behind it — every account 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 credit balance is empty. Regenerating the key will not help — the account needs to be recharged. 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 65 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 a verified example on every operation. 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.