Cost Control

Minimum requirements

Package	Minimum version
router	0.294.0
composition	0.54.0

Overview

Cost Control 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 Control allows assigning weights to fields and estimating query complexity before execution begins. When Cost Control is enabled, the router calculates and records costs for each incoming operation. In enforce mode, operations exceeding the configured limit are rejected immediately, and 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, and similar operations. 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. The router supports both static (estimated) and runtime (actual) cost measurements. Estimated cost is calculated before the execution, based on directive weights and list size estimates. Actual cost is calculated after the execution, using real list sizes returned by subgraphs.

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 Control is enabled in the router configuration:

security:
  cost_control:
    enabled: true
    mode: enforce
    estimated_list_size: 10
    max_estimated_limit: 1000
    expose_headers: true

Option	Environment Variable	Default	Description
`enabled`	`SECURITY_COST_CONTROL_ENABLED`	`false`	When true, the router calculates costs for every operation.
`mode`	`SECURITY_COST_CONTROL_MODE`	`measure`	`measure` calculates costs only; `enforce` rejects operations exceeding the estimated limit.
`max_estimated_limit`	`SECURITY_COST_CONTROL_MAX_ESTIMATED_LIMIT`	`0`	Maximum allowed estimated cost for a query. Rejection of operation happens only for positive values and when mode is ‘enforce’.
`estimated_list_size`	`SECURITY_COST_CONTROL_ESTIMATED_LIST_SIZE`	`0`	Default assumed size for list fields when no `@listSize` directive is specified. Required for Cost Control to work.
`expose_headers`	`SECURITY_COST_CONTROL_EXPOSE_HEADERS`	`false`	Adds `X-WG-Cost-Estimated` and `X-WG-Cost-Actual` response headers to every operation.

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 {
  searchFirst(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]
}

When specified on input object fields — weights on nested input fields are accumulated based on which fields the client provides in the query. Only the fields present in the input contribute to the cost:

input FindEmployeeCriteria {
  id: Int
  department: Department @cost(weight: 4)
  title: String @cost(weight: 3)
}

type Query {
  findEmployeesBy(criteria: FindEmployeeCriteria): [Employee]
}

Input object weights are evaluated per request, not cached with the query plan. Two requests using the same query but different input fields produce different cost estimates. When specified on a field returning a list, the list size multiplies the weight of this field:

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

When specified on a directive argument definition, it adds cost to every field where the directive is applied and the argument is active. See Weights on Directive Arguments.

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!): [Product] @listSize(slicingArguments: ["first"])
  search(limit: 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
    name
  }
}

When multiple slicing arguments are provided, the router uses the maximum value among them. Targeting specific child fields with sizedFields — when a field returns an object that contains list fields. This is useful for Cursor connection types where the parent field returns an object containing paginated lists. sizedFields option states that the size of the list returned by Connection.edges is determined by the value of one of the slicing arguments of the parent field:

type Query {
  usersConnection(first: Int, last: Int, before: ID): Connection! @listSize(
      slicingArguments: ["first", "last"]
      sizedFields: ["edges"]
    )
}

type Connection {
  edges: [Edge]      # Sized field — inherits multiplier from parent
  totalCount: Int    # Not a list, not in sizedFields
}

type Edge {
  cursor: ID
  node: Film         # Definition of this type left out in this example
}

With this configuration, a query like usersConnection(first: 5) applies the multiplier 5 only to the edges field. Without sizedFields, when @listSize is applied to a field returning a list, all immediate list children inherit the size estimate.

sizedFields can only reference fields that return lists within the parent type. The parent field must return a composite type (object, interface, or union).

Nested paths in slicingArguments

When the slicing value lives inside an input object, reference it with a dot-separated path. The first segment is the argument name. Each following segment is a field on the preceding input object. The leaf must be Int or Int!.

type Query {
  search(input: SearchInput!): [Result]
    @listSize(slicingArguments: ["input.pagination.first"])
}

input SearchInput {
  pagination: PaginationInput
  query: String
}

input PaginationInput {
  first: Int
  after: String
}

A query like search(input: { pagination: { first: 25 } }) resolves the multiplier to 25. Rules for nested paths:

Every intermediate segment must be a field that returns an input object. Lists and scalars cannot appear in the middle of a path.
Flat and nested paths can be mixed in the same slicingArguments list, for example ["limit", "input.pagination.first"].

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 Control was not enabled.
    }
    
    // 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 limit 1500"
    }
  ]
}

Telemetry

When Cost Control is enabled, the router can emit OpenTelemetry metrics for every operation. These metrics are available through both OTEL and Prometheus exporters, carrying the same operation-level attributes as other router metrics (wg.operation.name, wg.operation.type, wg.operation.protocol, wg.client.name, wg.client.version, http.status_code). For more details on exporting and querying, see Metrics & Monitoring. Cost metrics are disabled by default and must be explicitly enabled through cost_stats under the OTLP or Prometheus telemetry configuration:

telemetry:
  metrics:
    otlp:
      cost_stats:
        estimated_enabled: true
        actual_enabled: true
    prometheus:
      cost_stats:
        estimated_enabled: true
        actual_enabled: true

The environment variables corresponding to the config options above: METRICS_OTLP_COST_STATS_ESTIMATED_ENABLED METRICS_OTLP_COST_STATS_ACTUAL_ENABLED PROMETHEUS_COST_STATS_ESTIMATED_ENABLED PROMETHEUS_COST_STATS_ACTUAL_ENABLED

Metrics

Metric Name	Instrument Type	Description
`router.graphql.operation.cost.estimated`	Int64 Histogram	Estimated cost calculated before execution, based on directive weights and list size estimates.
`router.graphql.operation.cost.actual`	Int64 Histogram	Actual cost calculated after execution using real list sizes returned by subgraphs.

Those metrics use the exact same attribute set as other router request-level metrics (like router.http.requests, router.http.request.duration_milliseconds).

Cost metrics require both Cost Control to be enabled (security.cost_control.enabled: true) and the corresponding cost_stats toggle to be set. The actual metrics additionally require execution to complete so the router can observe real list sizes.

Using cost metrics

By default, histogram bucket boundaries are the following: 0, 10, 50, 200, 1000, 5000, 10000 The best practice is to assign the smallest possible weights to fields. It is better to keep costs low. If the estimate exceeds 10000, the value will be placed in the infinite bucket. Non-scalar fields have a default weight of 1. It is a good idea to pick custom weights close to 1. In measure mode, use cost metrics to understand the traffic before enabling enforcement:

Compare estimated vs. actual costs to configure estimated_list_size and @listSize.
Identify operations where the delta is consistently large — these benefit from more precise @listSize annotations.

Response Headers

When expose_headers is enabled, the router adds cost information to every response as HTTP headers. This is useful for debugging, client-side observability, and integrating cost awareness into API tooling.

Header	Description
`X-WG-Cost-Estimated`	The estimated cost calculated before execution, based on directive weights and list size estimates.
`X-WG-Cost-Actual`	The actual cost calculated after execution using real list sizes from subgraph responses.

Both headers are present on successful responses. On rejected responses (enforce mode), only X-WG-Cost-Estimated is set, since the query was not executed.

security:
  cost_control:
    expose_headers: true

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_control:
    enabled: true
    mode: measure
    estimated_list_size: 10

Pick Parameters for @listSize 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:

Using @listSize(assumedSize: N) on those specific fields
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): [User] @listSize(slicingArguments: ["first"])
  
  # Less ideal: cost uses default estimated_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.

Weights on Directive Arguments

@cost can be placed on arguments of custom directive definitions. When a field has such a directive applied, the weight of each active argument is added to the field’s cost.

directive @approx(tolerance: Int = 1 @cost(weight: -2)) on FIELD_DEFINITION

type Query {
  search(term: String!): [Result] @approx
}

In this example, the @approx directive has an argument tolerance with a cost weight of -2. Because tolerance has a default non-null value, it is considered active on every field where @approx is applied, even when the argument is not explicitly provided. The weight of -2 is added to the cost of Query.search. An argument is active when:

It has a non-null value at the directive usage site, or
It has a default value and is not explicitly set to null

When a directive is applied on fields of types implementing an interface, the router takes the maximum directive argument weight across all implementing types.

Getting Started

Concepts

Cosmo Connect

Cosmo ConnectRPC

Router

Studio

Control Plane

GraphQL / Federation

Deployments and Hosting

Minimum requirements

Overview

Key differences from the IBM specification

How Cost is Calculated

List Fields Multiply Cost

Configuration

Customizing Cost with Directives

The @cost Directive

The @listSize Directive

Nested paths in slicingArguments

Accessing Cost in Custom Modules

Error Responses

Telemetry

Metrics

Using cost metrics

Response Headers

Best Practices

Start with Measure Mode

Pick Parameters for @listSize Carefully

Annotate Expensive Resolvers

Nested Lists

Weights on Directive Arguments

​Minimum requirements

​Overview

​Key differences from the IBM specification

​How Cost is Calculated

​List Fields Multiply Cost

​Configuration

​Customizing Cost with Directives

​The @cost Directive

​The @listSize Directive

​Nested paths in slicingArguments

​Accessing Cost in Custom Modules

​Error Responses

​Telemetry

​Metrics

​Using cost metrics

​Response Headers

​Best Practices

​Start with Measure Mode

​Pick Parameters for @listSize Carefully

​Annotate Expensive Resolvers

​Design for Pagination

​Nested Lists

​Weights on Directive Arguments

Minimum requirements

Overview

Key differences from the IBM specification

How Cost is Calculated

List Fields Multiply Cost

Configuration

Customizing Cost with Directives

The @cost Directive

The @listSize Directive

Nested paths in slicingArguments

Accessing Cost in Custom Modules

Error Responses

Telemetry

Metrics

Using cost metrics

Response Headers

Best Practices

Start with Measure Mode

Pick Parameters for @listSize Carefully

Annotate Expensive Resolvers

Design for Pagination

Nested Lists

Weights on Directive Arguments