API Request Complexity

Overview

Our API implements a dual complexity system to ensure optimal performance and prevent resource exhaustion.

This system measures query complexity in two ways: Static Complexity (calculated before execution) and Dynamic Complexity (measured during execution).

Both complexity values are returned in the response headers to help you understand your queries:

x-complexity: Shows the static complexity score
x-dynamic-complexity: Shows the dynamic complexity score

Static Complexity

What is Static Complexity?

Static complexity is calculated before your query runs by analyzing the structure and parameters of your request. It estimates how resource-intensive your query will be, and is based on:

The base complexity value of each field
Multipliers based on pagination parameters (like first, skip)
The depth and nesting of your query

How Static Complexity is Calculated

Each API field has a predefined complexity value and optional multipliers.

The total complexity of a request is the sum of all field complexities.

The calculation follows this formula:

Field Complexity = (Base Value + Child Fields Complexity) × Total Multiplier

Where:

Base Value: The inherent complexity of the field (usually 1)
Child Fields Complexity: Sum of complexity from nested fields
Total Multiplier: Applied based on parameters like pagination size

Static Complexity Examples

Example 1: annotations Query

annotations(where: AnnotationWhere!, first: 50, skip: 0)

Base complexity: 1
Multiplier: first parameter (50) × 0.25 = 12.5
Total: 1 × 12.5 = 12.5

Example 2: appendManyAssets Mutation

appendManyAssets(data: { externalIDArray: ["id1", "id2", "id3"] })

Base complexity: 1
Multiplier: Length of externalIDArray (3)
Total: 1 × 3 = 3

Example 3: assets Query

Query:

query Query($where: AssetWhere!, $first: PageSize!, $skip: Int!) {
  assets(where: $where, first: $first, skip: $skip) {
    id                    # Complexity: 1
    issues {              # Complexity: 1
      assigneeUser {      # Complexity: 1
        id                # Complexity: 1
      }
    }
    currentStep {         # Complexity: 1
      type              # Complexity: 1
      status            # Complexity: 1
    }
    externalId            # Complexity: 1
  }
}

Variables:

{
  "first": 3,
  "skip": 0
}

Calculation:

Assets field base complexity: 1
Child fields complexity: 1 + (1 + (1 + 1)) + (1 + 1 + 1) + 1 = 8
Total before multiplier: 1 + 8 = 9
Multiplier: first parameter = 3
Final complexity: 9 × 3 = 27

This matches the x-complexity: 27 header you'd receive.

Static Complexity Limits

Queries with static complexity > 5,000 are rejected with error:

Query is too complex: [complexity_score]. Maximum allowed complexity: 5,000

Dynamic Complexity

What is Dynamic Complexity?

Dynamic complexity is measured during query execution by counting how many individual field resolvers are called. Unlike static complexity, this reflects the actual computational work performed.

How Dynamic Complexity Works

Every time the API processes a field in your query (whether it's a simple field like id or a complex nested object), the dynamic complexity counter increases by 1.

Dynamic Complexity Example

Using the same assets query but requesting 10,000 assets:

Query:

query Query($where: AssetWhere!, $first: PageSize!, $skip: Int!) {
  assets(where: $where, first: 10000, skip: 0) {
    id
    issues {
      assigneeUser {
        id
      }
    }
    currentStep {
      type
      status
    }
    externalId
  }
}

What happens during execution:

For each of the 10,000 assets returned:
- id field: +1 to dynamic complexity
- issues field: +1 per issue found
- assigneeUser.id: +1 per issue with assignee
- currentStep.type: +1 per asset
- currentStep.status: +1 per asset
- externalId: +1 per asset

Now, if each asset has an average of 2 issues, the dynamic complexity reaches quickly:

10,000 assets × (1 + 2 + 2 + 1 + 1 + 1) = 80,000

Dynamic Complexity Limits

When dynamic complexity exceeds a threshold during execution, the query is terminated with an error:

Dynamic complexity limit exceeded: query is too complex, try to reduce the number of nested fields or the amount of data requested.

For On-Premise Customers

If you're running an on-premise deployment, the dynamic complexity threshold can be customized through the DYNAMIC_COMPLEXITY_THRESHOLD environment variable. This allows you to adjust the limit based on your infrastructure capacity and performance requirements. Contact your system administrator to modify this setting if needed.