Change Data Capture Allocations

Concurrent Client Allocation

Default Allocations

If your org has no add-on licenses, default allocations apply and can't be exceeded. Each Salesforce edition provides a default allocation for the number of events delivered to CometD clients, including the empApi Lightning component. This allocation doesn’t apply to non-CometD subscribers, such as Apex triggers, flows, and processes. The default allocation is enforced daily to ensure fair sharing of resources in the multitenant environment and to protect the service. Default allocations aren’t part of the usage-based entitlement.

The number of delivered events to CometD clients is counted per subscribed client. If you have multiple client subscribers, your usage is added across all subscribers. For example, you have an Unlimited Edition org with a default allocation of 50,000 events in a 24-hour period. Within a few hours, 20,000 event messages are delivered to two subscribed clients. So you consumed 40,000 events and are still entitled to 10,000 events within the 24-hour period.

If you exceed the default event delivery allocation, you receive an error. For more information, see Streaming API Error Codes in the Streaming API Developer Guide. Event messages that are generated after exceeding the allocation are stored in the event bus. You can retrieve stored event messages as long as they are within the retention window of 72 hours.

Change Data Capture Add-On License and Usage-Based Entitlement

To remove the limit on the number of entities that you can select for change notifications, contact Salesforce to purchase the Change Data Capture add-on license.

If your org has the add-on license, your allocation for delivered events to CometD clients moves to a monthly entitlement model. The add-on increases the 24-hour allocation of delivered event notifications by 100,000 per day (3 million a month) as a usage-based entitlement. The entitlement gives you flexibility in how you use your allocations. The entitlement isn’t as strictly enforced as the default allocation. With the entitlement, you can exceed your 24-hour event delivery allocation by a certain amount. The entitlement is reset every month after your contract start date. Entitlement usage is computed only for production orgs. It isn't available in sandbox or trial orgs. For more information, see Usage-based Entitlement Fields.

Salesforce monitors event overages based on a calendar month, starting with your contract start date. If you exceed the monthly entitlement, Salesforce contacts you to discuss your event usage needs. The entitlement used for monitoring monthly event overages is the daily allocation multiplied by 30.

To increase the entitlement for event delivery, contact Salesforce to purchase the High-Volume Platform Events add-on.

The maximum event message size that Salesforce can publish is 1 MB. If your entity has hundreds of custom fields or many long text area fields, you could hit this limit. In this case, the change event message isn’t delivered and is replaced by a gap event message. For more information, see Gap Events.

Monitor Your Event Usage Against Your Allocations

Determine how to check event usage for your org.

For more information about the limit usage values that the limits REST resource returns, see Limits and List Organization Limits in the REST API Developer Guide.

Monitor 24-Hour and Daily Event Usage with PlatformEventUsageMetric

To get usage data for event publishing and CometD-client delivery, query the PlatformEventUsageMetric object. The usage metrics stored in PlatformEventUsageMetric are separate from the REST API limits values. The REST API limits resource returns the maximum and remaining allocations for platform events and change data capture events. PlatformEventUsageMetric contains actual event usage data broken down by type of event for platform events and change data capture events.

PlatformEventUsageMetric usage data is available for the last 24 hours, ending at the last hour, and for historical daily usage for the last 45 days. Use PlatformEventUsageMetric to get visibility into your usage trends.

For more information, see Monitor Change Event Publishing and Delivery Usage.

Monitor Hourly Event Delivery Usage with REST API

To monitor your org's event delivery hourly usage, make a REST API call to the limits resource every hour. The difference between the results obtained in the last 2 hours shows how many events were delivered in the last hour.

For example, you make a call at 12:00 PM and see that you have 40,000 events remaining. Then you run the same call at 1:00 PM and see that you have 38,500 events remaining. The returned responses indicate that 1,500 events were delivered to your CometD subscribers between 12:00 PM and 1:00 PM.

These results are examples of the responses that a GET request to the /services/data/v47.0/limits URI returns.

1First call result:
2{
3...  
4"MonthlyPlatformEvents" : {
5    "Max" : 50000,
6    "Remaining" : 40000
7  },
8
9...
10}
11 
12Second call result:
13{
14...  
15"MonthlyPlatformEvents" : {
16    "Max" : 50000,
17    "Remaining" : 38500
18  },
19
20...
21}