Cost Analysis

Protect the API from expensive operations by estimating query complexity before execution using @cost and @listSize directives

Overview

Cost analysis prevents a single GraphQL request from using too many system resources and slowing everything else down. A query requesting deeply nested lists can generate thousands of resolver calls and overwhelm subgraphs, while a simple field lookup costs almost nothing. Cost analysis allows assigning weights to fields and estimating query complexity before execution begins.

When cost analysis is enabled, the router calculates an estimated cost for each incoming operation based on the fields requested, their configured weights and expected list sizes. Operations exceeding the configured limit are rejected immediately. No subgraph requests are made, protecting the infrastructure from resource exhaustion.

The Cosmo Router implements the IBM GraphQL Cost Directive Specification, adapted for GraphQL Federation.

Key differences from the IBM specification

Weights use plain integers instead of stringified floats as defined in the IBM spec.

The IBM specification does not account for federation. Static cost is calculated based on the query plan, which uses a federation of subgraphs to create a chain of fetches. This chain is invisible at the supergraph level and may include entity calls, @requires fetches, etc. These are accounted for because they make certain queries more expensive.

When a field returns a list of objects with a type weight, the IBM spec does not multiply the type’s own weight by the list size — only the children’s costs are multiplied. This implementation multiplies both the type weight and children’s costs by the list size, resulting in higher cost estimates for list fields with weighted types. This is done because federation may trigger entity fetches between subgraphs.

Currently, only static (estimated) costs are supported. Dynamic (runtime) cost, calculated from actual data returned by subgraphs, is in active development.

How Cost is Calculated

The router walks through the query and sums the cost of each field.

By default, object types (including interfaces and unions) cost 1, scalar and enum fields cost 0. For example, this query has a cost of 4:

query {
  book(id: 1) {          # Book object: 1
    title                 # String scalar: 0
    author {              # Author object: 1
      name                # String scalar: 0
    }
    publisher {           # Publisher object: 1
      address {           # Address object: 1
        zipCode           # Int scalar: 0
      }
    }
  }
}

The router also accounts for weights assigned to the same field coordinate in different subgraphs, allowing specific resolvers to be weighted differently per subgraph.

List Fields Multiply Cost

When a field returns a list, the cost of that field and all its children is multiplied by the expected list size. Since the router cannot determine actual list sizes during planning, it uses estimates.

query {
  employees {            # List of Employee
    id
    department {
      name
    }
  }
}

With a default list size of 10, this query costs: 10 × (1 Employee + 1 Department) = 20

Configuration

Cost analysis is enabled in the router configuration:

security:
  cost_analysis:
    enabled: true
    mode: enforce
    estimated_limit: 1000
    estimated_list_size: 10

Option	Environment Variable	Default	Description
enabled	SECURITY_COST_ANALYSIS_ENABLED	false	When true, the router calculates costs for every operation.
mode	SECURITY_COST_ANALYSIS_MODE	measure	measure calculates costs only; enforce rejects operations exceeding the estimated limit.
estimated_limit	SECURITY_COST_ANALYSIS_ESTIMATED_LIMIT	0	Maximum allowed estimated cost. Only enforced when mode is enforce. 0 disables enforcement.
estimated_list_size	SECURITY_COST_ANALYSIS_ESTIMATED_LIST_SIZE	10	Default assumed size for list fields when no @listSize directive is specified.

Customizing Cost with Directives

Default weights work for many APIs, but the @cost and @listSize directives allow fine-tuning.

The @cost Directive

@cost assigns custom weights to types, fields or arguments that are more expensive than average.

When specified on a type — all fields returning this type inherit the weight:

type Address @cost(weight: 5) {
  street: String
  city: String
  zipCode: String
}

When specified on a field — only that field carries the weight:

type Query {
  search(term: String!): [Result] @cost(weight: 10)
}

When specified on an argument — adds cost for expensive argument processing:

type Query {
  users(filter: UserFilter @cost(weight: 3)): [User]
}

The @listSize Directive

@listSize provides better list size estimates than the global default.

Static size with assumedSize — when a field consistently returns a predictable number of items:

type Query {
  topProducts: [Product] @listSize(assumedSize: 5)
  featuredCategories: [Category] @listSize(assumedSize: 3)
}

Dynamic size with slicingArguments — when the list size is controlled by a pagination argument:

type Query {
  products(first: Int, after: String): ProductConnection 
    @listSize(slicingArguments: ["first"])
  
  searchResults(limit: Int!, offset: Int): [Result]
    @listSize(slicingArguments: ["limit"])
}

The router reads the argument value from the query to determine the multiplier:

query {
  products(first: 20) {   # Multiplier is 20
    edges { node { name } }
  }
}

When multiple slicing arguments are provided, the router uses the maximum value among them.

Accessing Cost in Custom Modules

In custom modules, the calculated cost is accessible through the operation context:

func (m *MyModule) Middleware(ctx core.RequestContext, next http.Handler) {
    // Get cost after planning
    cost, err := ctx.Operation().Cost()
    if err != nil {
        // Cost analysis not enabled or plan not ready
    }
    
    // Use estimated cost for custom logic (rate limiting, logging, etc.)
    if cost.Estimated > m.warningThreshold {
        m.logger.Warn("High cost operation", "cost", cost.Estimated)
    }
    
    next.ServeHTTP(ctx.ResponseWriter(), ctx.Request())
}

Use cases:

• Apply rate limiting based on query cost
• Log expensive operations for analysis
• Support billing based on query complexity
• Throttle requests during high-load periods

Error Responses

When a query exceeds the estimated cost limit (in enforce mode), the router returns a 400 status:

{
  "errors": [
    {
      "message": "The estimated query cost 1540 exceeds the maximum allowed estimated cost 1500"
    }
  ]
}

Best Practices

Start with Measure Mode

Start with mode: measure to calculate costs without rejecting queries. This reveals traffic patterns before enabling enforcement.

security:
  cost_analysis:
    enabled: true
    mode: measure
    list_size: 10

Pick Parameters for @list_size Carefully

The default list size significantly impacts cost calculations. If lists typically return 5–20 items, a default of 10 is reasonable. For fields that return large lists (100+ items), consider:

1. Using @listSize(assumedSize: N) on those specific fields
2. Requiring pagination with slicingArguments

Annotate Expensive Resolvers

Apply @cost to fields that trigger expensive operations:

• External API calls
• Complex computations
• Large database queries
• Fields that fan out to multiple subgraphs

type Query {
  # Calls external payment API
  paymentHistory(userId: ID!): [Payment] @cost(weight: 5)
  
  # Requires joining multiple tables
  analyticsReport(dateRange: DateRange!): Report @cost(weight: 10)
}

Design for Pagination

Pagination improves cost accuracy. slicingArguments provides precise multipliers based on client requests:

type Query {
  # Good: cost scales with requested page size
  users(first: Int!, after: String): UserConnection
    @listSize(slicingArguments: ["first"])
  
  # Less ideal: cost uses default list_size
  allUsers: [User]
}

Nested Lists

Nested list fields require special attention, as costs multiply:

query {
  departments {           # 10 departments
    employees {           # × 10 employees each = 100
      projects {          # × 10 projects each = 1000
        tasks {           # × 10 tasks each = 10000
          name
        }
      }
    }
  }
}

With a default list size of 10, this query costs over 10,000. Use @listSize to provide realistic estimates for deeply nested structures.

Features Not Yet Implemented

• Runtime (dynamic) cost measurement based on actual list sizes returned by subgraphs
• Cost telemetry — OTEL metrics and span attributes for cost values (cost.estimated, cost.actual, cost.delta)
• sizedFields in @listSize for applying list size estimates to specific child fields rather than all children
• requireOneSlicingArgument for validation of queries
• Input object fields when used as parameters of fields
• Arguments of directives are not accounted for weights