Complexity, our primary rate-limiting mechanism, defines 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

Limits

Complexity API rate limits are based on the complexity of an app's queries in a given period. Per-minute budgets reset 60 seconds after the first API call was made.

There are a few limits to keep in mind:

Integration action limits

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

Every integration recipe you run contributes to the monthly budget. Please note that integrations that return a failure via the severity code do not consume an action.

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.

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.

Nested queries

You can nest up to six queries at a time, but nesting queries inside other queries significantly increases the complexity of your call.

❗️

Only ask for the objects and properties you need, implement pagination, and avoid nested queries to keep your query complexity low.

The complexity of nested queries is calculated by multiplying the complexity of the subquery with the number of items returned via the limit param. It is crucial to add limits to each query to prevent exceeding the complexity limit.

Check out this 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
          }
        }
      }
    }
  }
}

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.

Avoiding timeouts

You can check the complexity of a query or mutation, implement pagination, avoid nested queries, and return only the necessary information in each API call to avoid timeouts. Additionally, some columns are more susceptible to timeouts because the server takes longer to return data from them (e.g. mirror columns). Avoid returning these columns unless it is required!

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. Doing so enables you to return the remaining complexity both before and after the query, the complexity of the query itself, and the amount of time before the limit resets.

mutation {
  complexity {
    query
    before
    after
  }
  create_item(board_id:1234567890, item_name:"test item") {
    id
  }
}

Pagination

Objects that support pagination take two arguments: page and limit. The page argument defines which page to retrieve from a set of data. It typically starts on page one.

The limit argument defines the maximum number of returned objects. Some objects have fields with built-in default limits. For example, the boards object has a default limit of 25. If you need a limit other than the default, or if you're querying a field that doesn't utilize the default limit, you can use the limit argument with the desired number of items to return.

Some API objects, like items_page and items_page_by_column_values use cursor-based pagination to paginate through large sets of data.

Whether you use limit, page, or cursor-based pagination, we highly recommend paginating through your queries to reduce the number of returned records. Doing so enables you to work efficiently and avoid reaching the complexity limit. With this approach, you lower the complexity of each query while still returning the same information in multiple calls.

Let's take a look at an example! The following query uses the limit and page parameters to return the first 10 updates in an account.

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

After returning the first 10 updates, 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
    }
  }	
}

📘

Join our developer community!

We've created a community specifically for our devs where you can search through previous topics to find solutions, ask new questions, hear about new features and updates, and learn tips and tricks from other devs. Come join in on the fun! 😎