API Settings are part of the Core Settings in Countly. To access them, in the Sidebar, go to Management > Settings, then select API from the Core Settings list.
The API Settings section allows you to configure the core behavior of how your Countly Server processes incoming data, manages write operations, handles caching, and enforces data limits. These settings directly affect server performance, data accuracy, and overall system behavior.
Changes to API settings require Global Admin privileges. Some settings can also be overridden at the application level through individual app management.
Batch Processing
Batch processing combines aggregated data operations into a single batch and commits them to the database at a set frequency. This can improve efficiency, reduce system load, and optimize performance by decreasing the number of individual write operations performed.
| Setting | Description | Default |
|---|---|---|
| Batch processing | Combines aggregated data writes together and commits them to the database at a specific frequency. When enabled, individual write operations are grouped for better performance. | Enabled |
| Batch write frequency | Defines how often batch writes are committed to the database. The value is in seconds. A lower value means more frequent writes, while a higher value reduces database load but may delay data availability. | 10 seconds |
| Batch writes on single process | When enabled, all processes send data to a single process to commit to the database. This is helpful if you have many CPU cores per instance, as it consolidates writes into one process. | Disabled |
| Count of lined up merges to be processed in parallel | Sets the number of user merge operations to process simultaneously. Do not increase this number unless your server is suffering from a long queue of unfinished merges. Processing more merges in parallel will increase resource usage. It is highly recommended to recheck your SDK implementation instead of increasing parallel processing. | 1 |
Cache Management
Cache management settings allow Countly to cache frequently accessed data and reduce redundant API calls. This helps optimize SDK API calls by caching responses for reuse, reducing database load and improving response times.
| Setting | Description | Default |
|---|---|---|
| Cache reads for SDK API calls | Some read operations that occur on each SDK call can be cached for reuse. Enabling this reduces the number of database queries for repetitive read operations. | Enabled |
| Cached reads update period | Determines how often the cache is refreshed with new data from the database. The value is in seconds. A lower value provides more up-to-date data but increases database load. | 60 seconds |
| Cached reads Time To Live | Specifies how long cached data is kept if it remains unused. After this period, unused cache entries are removed. The value is in seconds. | 600 seconds |
| Cached reads shared on single process | Shares all cached reads on a single process instead of each process maintaining its own cache. This is helpful if you have many CPU cores per instance, as it reduces memory usage across processes. | Disabled |
Data Limits
The Data Limits section allows you to define maximum thresholds for event tracking, segmentation, metrics, and session handling. These limits help protect server performance by preventing excessive data accumulation.
Increasing these limits may affect your server performance. Consult your system administrator before making changes to these values on high-traffic servers.
| Setting | Description | Default |
|---|---|---|
| Max unique event keys Performance Data Processing Interface |
The maximum number of unique event keys stored in the database. Increasing this number may seriously affect your server performance. | 500 |
| Max segmentation in each event Performance Data Processing Interface |
The maximum number of segmentation keys allowed per custom event. Increasing this number may affect your server performance. | 100 |
| Max unique values in each segmentation Performance Data Processing Interface |
The maximum number of unique values allowed within each segmentation key. Increasing this number may affect your server performance. | 1000 |
| Metric limit Performance Data Processing Interface |
The number of different metric values allowed per annual period. Increasing this number may affect your server performance. | 1000 |
| Maximal Session Duration Data Processing Interface |
The maximum session duration value (in seconds) allowed in any request. If a request contains a session duration higher than this value, it will be capped to this limit. | 86400 (24 hours) |
| Max length of array-type properties Performance Data Processing Interface |
If an event segment or custom user property value is an array and its length exceeds this limit, only the first N values (where N is this setting) will be retained. Any additional values will be discarded. | 10 |
Other API Settings
This section provides various configuration options for API behavior, data tracking, and system optimizations. These settings help fine-tune performance, security, and reporting functionalities.
| Setting | Description | Default |
|---|---|---|
| Safer API responses | When enabled, the server verifies key parameters and responds with an error or success status. This increases server overhead, so use it with care. | Disabled |
| Server URL (used in outgoing e-mails) |
The fully qualified domain name used in outgoing e-mails. It should be in the form of
http://SERVERNAME or https://SERVERNAME.
|
(empty) |
| Document export limit | The maximum number of lines in a CSV, PDF, or XLSX document exported in a single file. | 10000 |
| Offline mode | When enabled, API connections are disabled for e-mail report news, checking new SDKs, pinging external IPs, checking new blogs, and making Intercom connections. | Disabled |
| Regeneration interval for reports | The minimum report regeneration interval. If a report regeneration takes longer than the selected duration, it will be regenerated in the next closest interval. Available options: every 5 minutes, every 30 minutes, every hour, every 3 hours, every 12 hours, and every 24 hours. | Every hour |
| Request threshold (seconds) | Time (in seconds) before switching to the Report Manager if a drill, funnel, or other similar request takes too long to complete. This should not be longer than the HTTP timeout, which by default is 60 seconds. | 30 seconds |
| Sync plugin states | When enabled, toggling a plugin will propagate its state to all servers sharing the same database. This provides consistency but adds overhead for performing plugin state checks. | Disabled |
| Send a test e-mail to me | Sends a test e-mail to the e-mail address stored in your Countly account. Use this to verify that your e-mail configuration is working correctly. | — |
| Track city data Data Processing Interface |
Enables tracking city-level data. If disabled, city information will no longer be added or updated for users. | Enabled |
| Track country data Data Processing Interface |
Enables tracking country-level data. If disabled, country information will no longer be added or updated for users. | Enabled |
| Session cooldown (seconds) | The time (in seconds) between a session end and a new session start during which the server will extend the previous session instead of creating a new one. | 15 seconds |
| Total users | When enabled, the Total Users API is activated and used to override estimated total user counts in all reports. Enabling this provides additional overhead, so consult Countly before enabling it for high-traffic servers. | Enabled |
| Prevent duplicate requests | Stores and compares request hashes to prevent duplicate requests from being processed. | Enabled |
| Record metric changes | Records changes in metric values. This is required by the Total Users correction feature. Disable it only if you know you will not be using Total Users correction. | Enabled |
| Trim trailing and ending spaces Data Processing Interface |
When enabled, all trailing and ending spaces will be trimmed from all incoming data. | Disabled |
FAQ and Troubleshooting
How do I know if I should enable batch processing?
Batch processing is recommended for most deployments and is enabled by default. It reduces the number of individual database write operations, which improves overall performance. You should only disable it for debugging purposes or specific edge cases where real-time writes are critical.
How do I test my e-mail configuration?
Use the "Send a test e-mail to me" button in the Other API Settings section. This sends a test e-mail to the address associated with your Countly account. If the delivery fails, verify your SMTP or e-mail service configuration in your server setup.
How do I decide on appropriate data limits?
The default limits are suitable for most deployments. If you need to increase them, do so incrementally and monitor your server performance. Keep in mind that higher limits mean more data stored and processed, which directly impacts memory usage and query performance.