Credits & Limits

Rate Limits

Please note that there is a limit of 60 requests per minute set per API Key.

Looking at the different Subscriptions available to you, you might ask yourself:

How many credits do I really need?

What are Credits?

Each credit is worth roughly 1 data point.
On this page, you will learn the exact calculations that go on behind the scenes to figure out how many credits your queries require, as well as how to optimize your queries to redcue the number of credits you consume.

Credit Consumption Logic

The credit consumption logic for the Staking Data API is designed to measure and manage resource utilization when querying the API. Each query made to the API consumes a certain number of credits based on the complexity of the query and the amount of data returned. The goal is to provide an efficient and fair system for users while ensuring the API's performance and availability.

Counting Fields in the Query:

For each GraphQL query, the first step is to count the number of fields specified in the query. A field corresponds to a specific data point or attribute requested in the response. For example, in the following query:

{
   assets(limit: 100) {
      slug
      id
      createdAt
   }
}

The query has 3 fields specified (slug, id, and createdAt).

Calculating Credits per Query:

Once we have the number of fields, the API calculates the total credits consumed for the query. In general, each entry in the response counts as one data point. Therefore, if there are 100 asset entries returned, each with 3 fields, the API will generate up to 300 data points.

Number of Fields in Query * Number of Entries in Response = Total Data Points
3 * 100 = 300

The credits consumed by the query are the sum of the total data points and the number of fields specified in the query. Continuing with the example:

Total Data Points + Number of Fields in Query = Total Credits Consumed
300 + 3 = 303 credits

Actual Credits vs Max Credits

When calculating your credit needs, you should be aware that the calculations we show on this page are the maximum credits used per query. Credits are calculated based on how much data is returned rather than the theoretical number of datapoints requested. In this example, if there are only 50 Assets available, your credits used would be 50 * 3 + 3 = 153 instead of the theoretical max of 303.

Complex Queries with Nested Fields

The credit consumption logic becomes more complex when dealing with nested fields and multiple levels of data retrieval. Consider the following query:

{
   assets(limit: 10) {
      id
      slug
      logoUrl
      metrics(
         where: { metricKeys: ["reward_rate"], createdAt_lt: "2023-06-28" }
         limit: 10
         order: { createdAt: desc }
      ) {
         defaultValue
         createdAt
      }
   }
}

In this query, there are nested fields for the metrics field, with up to 20 metrics per asset, and up to 10 assets being queried. Each metric entry has 2 fields (defaultValue and createdAt), and each asset entry has 3 fields (id, slug, and logoUrl).

The calculation for credits consumed will be:

Metrics Fields  = 2  * 20  * 10 = 20 credits per asset
Assets Fields   = 3  * 10       = 30 credits
Asset Metrics   = 20 * 100      = 200 Credits

Total Fields in Query  = 5 (3 for asset, 2 for metrics)

Total Credits Consumed = Assets Fields + Asset Metrics + Total Fields in Query
                       = 30 + 200 + 5 
                       = 235 credits

Therefore, the query will consume a maximum of 235 credits in total.

Optimize Your Consumption

There are a few key ways to optimize your credit consumption

1. Only Query Fields which are necessary

   As you can see from the calculations above, you pay for each field you query whether you end up using it or not. One of the main ways to cut down your credit consumption, is to be critical which fields you need to query.
   For example, if you want to query the historical price of an asset as seen below, you do not need to request the metricKey field, as you are explicitly stating you only want the price metrics.

   {
        assets(where:{slugs:["cosmos"]}, limit: 1) {
            slug
            metrics(where:{metricKeys:["price"], createdAt_lt:"2023-08-01"}, limit:500){
                defaultValue
                createdAt
            }
        }
    }

   By not including the metricKey field in the query, you are saving up to 500 credits for each time you run the query.

2. Be explicit with what data you require

   Another good way to cut down on credit consumption is to be clear on what data you want to request exactly. If you are able to clearly state which datapoints you want, you can cut down on the credit consumption considerably. Let's assume you want the reward_rate of an asset at the end of each month, then rather than requesting all of the historical data for reward_rate you can run a query such as:

    {
        assets(where: { slugs: ["cosmos"] }, limit: 1) {
            slug
            metrics(
                where: { metricKeys: ["reward_rate"],createdAt_gt:"2023-07-01", createdAt_lt: "2023-08-01" }
                order: { createdAt: desc }
                limit: 1
            ) {
                defaultValue
                createdAt
            }
        }
    }

   By not including the metricKey field in the query, you are saving up to 500 credits for each time you run the query.