Guide
Credits and quota
Every served request costs credits, by one published formula, and reports what it cost.
The formula
credits = ( base
+ ceil(rows_returned / 1000) × per_1k_rows
+ filter_without_index × (filter clauses no index serves) )
× response factor (200 → 1, 304 Not Modified → 0.1, cache hit → 0.25)The result is rounded half-up to a thousandth of a credit.
The weights base, per_1k_rows and filter_without_index belong to the dataset: its publisher sets them. The defaults are 1, 2 and 5.
A filter no index serves is one on a field without an index, or one using contains, ends_with or matches.
No request is charged the cache-hit factor yet: it is published now so that it adds no surprise later.
With the default weights
| Request | Credits |
|---|---|
| A page of 10 rows | 3 |
| A page of 1,000 rows | 3 |
| A page of 1,001 rows | 5 |
| A page of 50,000 rows | 101 |
| An unchanged page, answered 304 | 0.1 |
| A page of 10 rows filtered with contains | 8 |
Every page reports its cost in credits_consumed. Every response to a request that passed authentication and the rate limit carries the X-Credits-Consumed header.
Quota
A quota is a number of credits per hour, day or month, set by your organisation's plan. A key can also be given a credit limit of its own, up to the organisation's.
| Header | Meaning |
|---|---|
X-Credits-Consumed | The credits this request consumed, by the published formula. |
X-Quota-Limit | The credits of the binding quota for the period. |
X-Quota-Remaining | The credits of that quota left after this request. |
X-Quota-Reset | Seconds until the quota period ends. |
X-Quota-Period | The quota period: hour, day or month. |
X-Request-ID | The ID this request's metering event is recorded under. |
A request that would pass the quota is refused with 429 and the code quota_exceeded. Its details say which quota, the period, what is left, when it resets and where to get more.
Requests with a sandbox key are never counted.