GraphQL Query Cost Rate Limiting

Counting GraphQL requests is meaningless: one document can request three fields or three million, and both arrive as a single POST /graphql. Pricing the document before executing it — the approach the protocol-specific throttling guide generalises — replaces the request count with a number that tracks the work the query will actually cause.

The problem in concrete numbers

A public API exposes organisations, their repositories, and each repository’s issues. This document is one request:

query Deep {
  organisation(login: "acme") {
    repositories(first: 100) {
      nodes { issues(first: 100) { nodes { comments(first: 100) { nodes { body } } } } }
    }
  }
}

Read it as work rather than as text: 100 repositories × 100 issues × 100 comments = one million resolver invocations, from a single HTTP request that a request counter scores as 1. A limit of 5,000 requests per hour permits five billion resolver calls per hour if clients write documents like this, which is why every production GraphQL API eventually adopts cost analysis.

Decision matrix: which cost model

Start with static node count plus a depth cap, then layer per-field weights on the handful of fields that are genuinely expensive — a search field hitting an external index, a mutation that fans out to three services. Chasing exactness with post-execution measurement costs more than it saves and leaves clients unable to predict anything.

Step-by-step implementation

• Add a depth limit first — it is one line and stops the pathological cases immediately.
• Implement static cost analysis in the validation phase, before execution begins.
• Assume a default page size for list fields with no first/last argument; require pagination arguments on large lists.
• Set maxSingleCost so no one document can drain a whole budget, and return a distinct error for it.
• Charge the cost atomically against the caller’s bucket, using the shared store the rest of your limits use.
• Return cost, remaining, and resetIn in extensions on every response, success or failure.
• Mirror the values into X-RateLimit-* headers so proxies and dashboards can see them.
• Publish the price list and the budget in your API documentation before enforcing.

// cost-plugin.ts — Apollo Server plugin: price, charge, report.
import { GraphQLError } from "graphql";
import { getComplexity, simpleEstimator, fieldExtensionsEstimator } from "graphql-query-complexity";

const MAX_SINGLE_COST = 5_000;
const BUDGET_PER_HOUR = 50_000;

export const costPlugin = (consume: (key: string, cost: number) => Promise<Verdict>) => ({
  async requestDidStart() {
    return {
      // Runs after validation, before execution: nothing has hit a resolver yet.
      async didResolveOperation({ request, document, schema, contextValue }) {
        const cost = getComplexity({
          schema, query: document, variables: request.variables,
          estimators: [
            // Per-field weights declared in the schema take precedence...
            fieldExtensionsEstimator(),
            // ...otherwise every field costs 1, multiplied by enclosing list sizes.
            simpleEstimator({ defaultComplexity: 1 }),
          ],
        });

        if (cost > MAX_SINGLE_COST) {
          throw new GraphQLError(
            `Query cost ${cost} exceeds the ${MAX_SINGLE_COST} maximum for a single operation.`,
            { extensions: { code: "QUERY_TOO_EXPENSIVE", cost, max: MAX_SINGLE_COST } },
          );
        }

        const v = await consume(`gql:${contextValue.apiKey}`, cost);
        contextValue.rateLimit = { cost, remaining: v.remaining, resetIn: v.resetSeconds };

        if (!v.allowed) {
          throw new GraphQLError("Rate limit exceeded", {
            extensions: {
              code: "RATE_LIMITED", cost, remaining: 0,
              retryAfter: v.retryAfterSeconds, budget: BUDGET_PER_HOUR,
            },
          });
        }
      },

      // Always report the balance, so clients can self-pace instead of probing.
      async willSendResponse({ contextValue, response }) {
        const rl = contextValue.rateLimit;
        if (!rl || response.body.kind !== "single") return;
        response.body.singleResult.extensions = {
          ...response.body.singleResult.extensions,
          rateLimit: { cost: rl.cost, remaining: rl.remaining, resetIn: rl.resetIn },
        };
        response.http.headers.set("X-RateLimit-Limit", String(BUDGET_PER_HOUR));
        response.http.headers.set("X-RateLimit-Remaining", String(rl.remaining));
        response.http.headers.set("X-RateLimit-Reset", String(rl.resetIn));
      },
    };
  },
});

Declaring weights in the schema keeps the price next to the field it prices, which is the only way the two stay in sync:

type Query {
  # A cheap primary-key lookup.
  repository(owner: String!, name: String!): Repository @cost(complexity: 1)

  # An external search index: expensive regardless of page size.
  search(query: String!, first: Int = 20): SearchResults
    @cost(complexity: 50, multipliers: ["first"])
}

type Mutation {
  # Fans out to billing, email, and audit services.
  createSubscription(input: SubscriptionInput!): Subscription @cost(complexity: 200)
}

Gotchas and edge cases

• Unbounded lists default to something. A list field with no pagination argument must be priced with an assumed page size, or an attacker simply omits first. Better: make pagination arguments required on any list that can exceed a page.
• Fragments and aliases multiply. The same expensive field aliased ten times is ten field selections; a cost analyser that deduplicates by field name under-prices it badly. Count selections, not names.
• Introspection is not free. A full introspection query on a large schema is genuinely expensive. Price it, cache the result, or disable introspection in production.
• Mutations priced structurally are wrong. createSubscription is one node and fifty times the work of a field read. Weight mutations explicitly.
• 200 OK hides the rejection. GraphQL returns errors inside a 200 by default, so clients that check only the HTTP status never learn they were limited. Always set the extensions.code, and mirror the state into headers.
• Batched operations bypass a per-request charge. An array of ten documents in one HTTP request must be priced as the sum of ten, not as one.
• Persisted queries change the calculus. If only allow-listed documents can be executed, their costs are known in advance — precompute and cache the price by document hash instead of analysing on every request.

Verification and testing

# 1. A deliberately expensive document must be refused before execution.
curl -s https://api.example.com/graphql -H "Content-Type: application/json" \
  -H "X-API-Key: gql_test" -d '{"query":"{ organisation(login:\"acme\"){ repositories(first:100){ nodes{ issues(first:100){ nodes{ id } } } } } }"}' \
  | jq '.errors[0].extensions'
# { "code": "QUERY_TOO_EXPENSIVE", "cost": 10101, "max": 5000 }

# 2. Every successful response reports the balance.
curl -s https://api.example.com/graphql -H "Content-Type: application/json" \
  -H "X-API-Key: gql_test" -d '{"query":"{ repository(owner:\"acme\", name:\"api\"){ name } }"}' \
  | jq '.extensions.rateLimit'
# { "cost": 2, "remaining": 49998, "resetIn": 3512 }

Add a unit test asserting the price of a fixed set of representative documents. When someone adds a list field without a page-size multiplier, that test changes, which is the earliest possible warning that your model has drifted from your schema.

Frequently Asked Questions

Related

• Protocol-Specific Throttling — the parent guide on cost functions across protocols.
• WebSocket Message Rate Limiting — the connection-scoped counterpart for subscriptions.
• Token Bucket Implementation — the bucket the computed cost is charged against.
• Rate-Limit Response Headers — mirroring the budget into transport headers.