Credits per API

Every API has a price in credits, and a plan is a number of credits a month. A calculation costs 1, a written reading 5, a scan across time 10 or 20, and a PDF 500 or 1,000. The table below is the whole list, and it is the one the gateway charges from.

Every plan can call every API. No route needs a higher plan; the credits do the limiting. The one exception is PDFs, which are not on the Free plan.

The rules

• A refused request costs nothing. The credits are reserved before the calculation starts and given back the moment the request is refused — a validation error, a bad key, a rate limit, a quota stop, a failure on our side. Refusals still show in your usage as errors; they are not on the bill.
• A cached answer costs the same as a fresh one. Identical requests are answered from a 24-hour cache, and X-KJ-Cache: hit says which you got. The cache makes the answer fast, not free.
• What you select does not change the price. Divisional charts cost 1 whether you ask for sixteen or three.
• Two routes are priced per unit, because they are several requests in one. A match batch costs 1 credit per pair, and the whole kundli report 5 credits per part — 40 for all eight, 15 for three. Either costs exactly what the separate requests would; what it saves is the round trips. The whole price is reserved up front, so one that does not fit in what you have left is refused and costs nothing.
• Time zone and the reference tables are free. They still want a key and still spend a token from your per-minute bucket — cheap, not free to flood. GET /v1/health wants neither.

What a request cost

The answer says so itself:

• meta.credits on every JSON answer — what this request cost;
• X-KJ-Credits on every metered answer, a PDF included — the same number as a header;
• X-KJ-Credits-Remaining — what is left of the month and of your credit packs together. Sent to secret keys only: a publishable key sits in a web page, and your balance is not your visitors’ business.

GET /v1/reference/credits returns this table as JSON, as it is in force right now.

The table

Prices can change. When one does, this page and GET /v1/reference/credits change with it, and meta.credits on each answer always says what that answer cost.

PDFs

A PDF costs far more than the same content over the API, on purpose: rendering is what costs us. PDFs are on every paid plan and not on Free, and each one also counts against a monthly cap that resets on your billing day with the credits:

The same PDF asked for again within 24 hours comes back from the cache without using the cap; it still costs its credits. Past the cap the answer is 402 pdf_quota_exceeded and every other route keeps working. The PDF routes are closed to publishable keys. The PDF guide has the rest.

Credit packs

A pack is extra credits on the plan you are already on, bought from the dashboard’s Plan page when a month runs over. Free has no packs — it upgrades — and Enterprise has what its contract says.

• Your plan’s monthly credits are spent first, then packs, oldest first.
• A pack lasts 12 months from the day it is paid for. It does not reset with the month.
• A pack is not refundable and cannot be moved to another account.
• A pack counts only while you are on the plan you bought it on, or a higher one. On a lower plan it is frozen, not lost: it counts again when you move back up, until it expires.
• Packs add credits only. They do not raise the monthly PDF cap.
• A publishable key does not draw on packs unless you allow it for that key on the dashboard’s Sites page, and it spends at most its daily cap — a tenth of your plan’s monthly credits unless you set another. A publishable key is in your page’s source, so these are what limit what a copied one can cost; see Authentication.

A pack credit costs more than a credit on the plan above, so past a point upgrading is the better deal — on Starter, beyond about 107,000 credits a month. See pricing.

Two limits, two different failures

Rate is how fast. Each key has a token bucket: it refills at your plan’s req_per_min and holds burst tokens, so a short spike is absorbed and a sustained flood is not. Over it, 429 rate_limited with a Retry-After header. Every response carries the state of the bucket, and what the answer cost:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1789504694
X-KJ-Credits: 1
X-KJ-Credits-Remaining: 199412
X-KJ-Cache: miss
X-KJ-Engine: 0.15.2
X-KJ-Plan: growth
X-KJ-Request-Id: 97f48252-8b54-4a7e-9e81-eb06d5a3ce02

X-KJ-Plan is the plan the answer was served under. It is worth reading rather than assuming: if a plan was given to you with an end date and that date has passed, this says free from that moment, which is the honest answer to why the limits changed.

Five routes do much more work than the rest — /v1/panchang/month, /v1/ephemeris/month, /v1/transit/scan, /v1/transit/events and /v1/match/batch — and they, with the PDF routes, share a second ceiling of 10 requests a minute on every plan. A credit price does not stop ten month-long scans arriving in the same second; this does. /v1/transit/scan and /v1/match/batch are also closed to publishable keys.

Quota is how much this period, which runs from your billing day to the same day next month. With nothing left, or not enough left for the request you sent, the answer is 402 quota_exceeded until your billing day comes round, you buy a pack or you upgrade. Nothing is throttled silently and nothing extra is billed without you choosing it.

What you can spend is the credits your plan includes, plus anything added to your account — a standing monthly extra, or a one-off for a single month — and then your credit packs. The dashboard’s Plan page shows the parts separately, and the 402 names the total it actually enforced rather than the plan’s own figure.

The rate is per key and the quota per account, and both cost nothing when they refuse you. A publishable key has one more bucket: the rate is applied per site as well as per key, so a kj_pub_… key on a busy page cannot spend the whole key’s minute. See Authentication for the rule.

Forecasting a bill

Add up what a page asks for:

a kundli page that renders the chart, the dasha and the yogas = 3 credits per visitor, plus 0 for the reference tables it renders labels from. Add the lagna reading and it is 8.

Cache what you can at your end. Identical requests you make twice in a day are a cache hit on our side and still cost their credits, so the cheapest request is the one you did not need to send.

See pricing for the plans and the billing FAQ.