Rate Limits

Our primary rate limiting mechanism is a construct called complexity to define the cost of each query made.

API consumers are subject to different rate limits depending on the token used to make the call. You can use two different types of tokens:

• API tokens belonging to apps, generated through seamless auth or OAuth
• API tokens belonging to a specific user and generated in the developers or admin section

Complexity API rate limits are based on the complexity of an app's queries in a given period. There are a few limits to keep in mind:

• Single-query limit: A single query is limited to 5,000,000 (5M) complexity points
• There are some additional limits based on what type of client is accessing the API:
  • App tokens: Reads and writes are limited to 5M complexity points per minute each
  • API playground: Reads and writes are limited to 5M complexity points per minute each or 1M for trial/free accounts
  • Personal API tokens: Reads and writes have a combined budget of 10M points per minute or 1M for trial and free accounts
• These operations have additional rate limits:
  • Duplicate a group
  • Duplicate a board
  • Return items from an account

Default complexities

Specific queries have default complexities regardless of their results. For example, querying most objects without limits (i.e., all boards, items, groups, etc.) is calculated as a complexity of 1,000. However, specific objects (like updates) have a default complexity of 25.

Complexity of nested queries

Nesting queries inside other queries significantly increases the complexity. The maximum number of nested queries allowed is 6.

When calculating the complexity of nested queries, multiply the complexity level of each query together. Note: It is crucial to add limits to each query to prevent exceeding the complexity limit.

Here's an example of a deeply nested query:

query {
  updates {
    updated_at
    created_at
    item_id
    replies {
      id
      text_body
      creator {
        birthday
        teams {
          name
          users (ids: [12345, 54321, 01234]) {
            id
          }
        }
      }
    }
  }
}

Integration action limits

Integration recipes on your board are subject to a separate integration action limit that provides several allotted integration actions each month. Integration apps and webhooks consume actions from this limit when they run. 

Every integration recipe that you run contributes to the monthly budget. If the integration recipe uses our API on the backend, it will also use some of the per-minute complexity limits.

Calculating complexity

Complexity levels are calculated based on the query. Each call will have a different level of complexity depending on the structure of the query, including limits and nested queries.

To keep your query complexity low, only ask for the objects and properties you need. You can also reduce the complexity by implementing pagination.

For example, you would calculate the complexity of a query to return 20 items from 10 boards by adding together the complexity levels of each query. In the example below, the complexity is 310.

query {
  complexity {
    query
  }
  boards (limit:10) {
    items (limit:20) {
      id
		}
	}
}

If you make calls with deeply nested queries, the complexity will increase. In the example below, the complexity is 5,110.

query {
  complexity {
    query
  }
	boards (limit:10) {
		items (limit:20) {
			id
      group {
        id
      }
      creator_id
      name
      column_values {
        id
      }
		}
	}
}

Exceeding the limit

The complexity limit starts at 5,000,000 for a single query. Each minute the complexity limit resets to 10,000,000 (or 5,000,000 for reads and 5,000,000 for writes for apps).

There are also mutation-specific rate limits based on the number of API calls made within a minute for the following mutations:

• duplicate_group
• duplicate_board

The mutations above will have an additional rate limit of 40 mutations per minute. If you exceed this limit, you will receive a 429 HTTP response code with "Call limit exceeded for DuplicateGroup" or "Call limit exceeded for DuplicateBoard" error message.

If you exceed either of these limits, the query will return an error in the "errors" field.

Timeout policy

All API calls are subject to a 60-second timeout policy.

If you can't make a query and return the data within 60 seconds, our servers will abandon the request. It is essential to keep this policy in mind if you are making heavy queries to return a lot of data or have a slow network connection.

We recommend using limits, implementing pagination, avoid nesting queries, and returning only necessary information in each API call to avoid timeouts.

If you run into a timeout, try returning fewer items or columns in the API call. Some columns, like mirror columns, are more susceptible to timeouts because the server takes longer to return data from them. Avoid returning these columns unless it is required!

Avoiding the complexity limit

Checking the complexity of a query or mutation

Since accounts have complexity per minute limits, understanding the complexity level of each query plays a significant role when making queries. You can prevent hitting the complexity limit by calculating the complexity of your query or mutation in advance.

The best way to calculate the complexity is to add the complexity field to your queries. To see how to query complexity, please see the complexity section.

Pagination

To work efficiently and avoid reaching the complexity limit, we recommend adding limits to your query to return the same number of records each time.

We established a default limit of 25 records for select fields. Not all fields utilize this limit, so we recommend using limits in all of your API calls to avoid timeouts.

Objects that support pagination take two arguments: limit and page. The limit argument defines the maximum number of returned objects, and the page defines which "page" to retrieve.

With this approach, you lower the complexity of each query while still returning the same amount of information (in more calls).

Here's a query that uses the limit and page parameters to return the first 10 updates in an account:

query {
	updates (limit:10, page:1) {
		id
		items {
			id
		}
	}	
}

You can change the page argument to return the next 10 items (ie, the 11th to 20th update):

query {
	updates (limit:10, page:2) {
		id
		items {
			id
		}
	}	
}

Happy paginating!

📘

Do you have questions?

Join our developer community! You can share your questions and learn from fellow users and monday.com product experts.

Don’t forget to search before opening a new topic!