---
title: "Rate Limiting GraphQL APIs by Calculating Query Complexity"
description: "Shopify’s GraphQL Admin API uses calculated query costs to address two limitations of request-based rate limiting: identical credits for responses of different sizes and equal treatment of reads and side-effecting writes. The server statically analyzes each query, assigning one point to objects and interfaces or unions, zero to scalars and enums, two plus the requested object count to connections, and 10 to mutations. Clients receive 50 points per second up to a 1,000-point limit, while responses expose requested and actual costs; when fewer connection records are returned, the difference is refunded. The post reports a linear correlation between calculated query complexity and execution time, giving Shopify more predictable load for infrastructure scaling and a way to identify performance outliers."
---

# Rate Limiting GraphQL APIs by Calculating Query Complexity

[Shopify](https://yomu.fyi/company/shopify) · 2023-10-18 · Jun 22, 2021

**Type:** Explainer

## Summary

Shopify’s GraphQL Admin API uses calculated query costs to address two limitations of request-based rate limiting: identical credits for responses of different sizes and equal treatment of reads and side-effecting writes. The server statically analyzes each query, assigning one point to objects and interfaces or unions, zero to scalars and enums, two plus the requested object count to connections, and 10 to mutations. Clients receive 50 points per second up to a 1,000-point limit, while responses expose requested and actual costs; when fewer connection records are returned, the difference is refunded. The post reports a linear correlation between calculated query complexity and execution time, giving Shopify more predictable load for infrastructure scaling and a way to identify performance outliers.

## Context

Request-based rate limiting gives clients the same credit cost regardless of how much data a response returns, and treats reads and side-effecting mutations equally even though they can impose different server loads. The system also needs to protect API stability from abusive requests, accidental infinite loops, and bursts.

## Approach / What changed

The API statically analyzes GraphQL queries and assigns costs by type: objects and interfaces or unions cost one point, scalars and enums cost zero, connections cost two points plus the number of expected returned objects, and mutations cost 10 points. Clients receive 50 points per second up to 1,000 points. The API reports requested and actual costs, refunds differences when fewer records are returned, and can include per-field costs when requested with the X-GraphQL-Cost-Include-Fields: true header.

## Takeaways

- GraphQL connections cost two points plus the number of objects the query expects to return; cursor and pageInfo do not add separate costs.
- Requested query cost is calculated before execution, while actual cost is calculated during execution and can be lower when a connection returns fewer records.
- The reported linear correlation between query complexity and execution time supports more predictable infrastructure scaling and helps identify performance outliers.

**Tags:** [GraphQL](https://yomu.fyi/topic/graphql), [Performance](https://yomu.fyi/topic/performance), [REST APIs](https://yomu.fyi/topic/rest-api), [Scalability](https://yomu.fyi/topic/scalability)

- Source: [Shopify](https://shopify.engineering/rate-limiting-graphql-apis-calculating-query-complexity)
- Source URL: https://shopify.engineering/rate-limiting-graphql-apis-calculating-query-complexity
- Ingested by Yomu: 2026-08-30T15:30:05.113Z

[Read original post](https://shopify.engineering/rate-limiting-graphql-apis-calculating-query-complexity)