API settings

The API has a number of configuration settings that control its behaviour at the site level. Site Administrators can configure the general API settings for your site by navigating to Quick-access menu > Development > API > API settings.

Only users with the totara/api:managesettings capability are able to configure API settings at the site level. By default this includes Site Administrators and Site Managers. Tenant users will be limited to making changes at the client level.

The table below describes the API settings that can be defined at the site level. Some settings can also be configured at the individual client level.

For more information about rate limits and query complexity, please see the developer documentation.

Setting	Description	Notes
Site rate limit	Set the maximum query complexity cost for all clients per minute.	The default value is 500,000.
Client rate limit	Set the maximum query complexity cost per minute for a single client.	You can configure this limit for individual clients by editing their settings. The default value is 250,000.
Maximum query complexity	Set the maximum complexity allowed for a single query.	The default value is 6,000.
Maximum query depth	Set the maximum depth allowed for a single query.	The default value is 15.
Default token expiration	This sets the default length of time tokens will be valid when adding new API clients. Use the two dropdown menus to set the value and the unit of time (e.g. hours, days, weeks).	You can configure the token expiry for each client by editing their settings. The default length of time is 24 hours.
Default error response	This setting determines how much information will be provided in API responses when errors occur. Select one of the following options: None: API responses will not return any specific information about the error Normal: API responses will return specific information about why the error occurred Developer: API responses will return specific information about why the error occurred, including a full stack trace	The default option is Normal.

Setting

Description

Notes

Site rate limit

Set the maximum query complexity cost for all clients per minute.

The default value is 500,000.

Client rate limit

Set the maximum query complexity cost per minute for a single client.

You can configure this limit for individual clients by editing their settings. The default value is 250,000.

Maximum query complexity

Set the maximum complexity allowed for a single query.

The default value is 6,000.

Maximum query depth

Set the maximum depth allowed for a single query.

The default value is 15.

Default token expiration

This sets the default length of time tokens will be valid when adding new API clients. Use the two dropdown menus to set the value and the unit of time (e.g. hours, days, weeks).

You can configure the token expiry for each client by editing their settings. The default length of time is 24 hours.

Default error response

This setting determines how much information will be provided in API responses when errors occur. Select one of the following options:

None: API responses will not return any specific information about the error
Normal: API responses will return specific information about why the error occurred
Developer: API responses will return specific information about why the error occurred, including a full stack trace

The default option is Normal.

API settings

What's Next