Credits and limits

What a call costs

A call costs its type times the dataset class. A lookup of one company's KPIs is 1 x 2 = 2 credits; the CPI board is 1 x 1 = 1.

/v1/datasets/cost prices a described call without running it, with no key and no account:

curl "https://api.gloom.sh/v1/datasets/cost?endpoint=awards.detail&id=1111111111111111111111111111111111111111"

Headers

• X-Credits-Cost: credits this call spent.
• X-Credits-Remaining: credits left in the current period.
• X-Plan: the account's plan.
• X-Request-Id: quote it when you write to us.
• Retry-After: seconds to wait, on 429 and 503.

Your balance

Two routes read the key's account and cost nothing:

• GET https://api.gloom.sh/v1/datasets/account: plan, status, the current period, credits included, used and remaining, and the plan's limits.
• GET https://api.gloom.sh/v1/datasets/usage: the same balance, plus the period's requests, credits, rows and errors by dataset.

When a call is charged

• Credits come with a plan, each period. An account without a plan has none, and its keys get 402 plan_required.
• Credits are spent once the key, plan and parameters check out, before the data is read.
• Bad parameters (400) and refused calls (401, 402, 403, 429) cost nothing.
• A server error (503) refunds the call; X-Credits-Cost shows what was finally charged.
• A 404 for an award or filing that does not exist keeps its charge.

Rate limits

Each plan has a budget per minute, counted in credits: a 10-credit call uses 10 of it. Over the budget, calls get 429 rate_limited with Retry-After.

At the credit limit

When a period's credits run out, calls get 429 credits_exhausted until the next period; Retry-After counts the seconds. Unused credits do not carry over.

Point in time

Every plan reads with asOf.