The Salesforce Platform offers an extensive set of APIs for accessing the data in your org, and you can read about them in our blog post Accessing Object Data with Salesforce Platform APIs. There are two sides to using the Salesforce Platform APIs. First, you need to develop against the APIs by building client applications that consume those APIs. Second, you need to monitor the use of these APIs to ensure that everything runs smoothly in production. In this post, we’ll introduce the API limit and entitlement, how to monitor them, and how you can view API requests.

Understanding API limit and entitlement

Salesforce is a multi-tenant platform with multiple orgs running on shared infrastructure (the Trailhead module Salesforce Core Infrastructure describes this architecture). We need to carefully manage platform resources to both ensure optimal performance for all users and provide fair access to system resources. This includes APIs, and we achieve this by the use of API limits.

Daily API Request Limit

This is the total number of API calls to the REST API, the SOAP API, the Bulk APIs, and the Connect API that your org is entitled to within a rolling 24-hour period. For paid org editions, such as Enterprise Edition, this starts at 100,000 requests per 24-hour period and increases based on the licenses your org is provisioned with. You can also purchase additional API calls in increments ranging from 200 through 10,000 per 24-hour period. This limit is a soft limit, and we allow your org to exceed it as described below.

Monthly API Entitlement

This is the number of API calls that your org is entitled to over a 30-day period. It is your Daily API Request Limit aggregated into a 30-day limit. There is no enforcement against the Monthly API Entitlement.

You can read more about these limits in this quick reference.

Limit enforcement

The diagram below illustrates how Salesforce enforces the above API limits.

Salesforce monitors your API usage based on the number of API requests your org has received. This is tracked against both the Daily API Request Limit and the Monthly API Entitlement.

The Daily API Request Limit is a soft limit and your org is allowed to exceed it. When this happens, further API calls will not be blocked, but they will continue to be processed if it safe to do so.

If your API requests continue to increase, then at some point, a system protection limit will be enforced and all subsequent API calls blocked. The response will have an HTTP status code of 403 and a REQUEST_LIMIT_EXCEEDED error code to indicate this. API calls will only be unblocked when your Daily API Requests, as measured over the preceding 24-hours, falls back under this limit.

Monitoring your API limit and entitlement

The soft limit behavior of the Daily API Request Limit means that are you not blocked due to temporary and/or unplanned bursts in API activity — for example, when a production issue results in a runaway process that burns through API calls unexpectedly, or an unanticipated spike in traffic results from an over-performing campaign. However, you should not plan your normal business volumes based on exceeding your Daily API Request Limit as this is intended for exceptional circumstances.

Managing your API limit and entitlement

You should regularly monitor your API usage against both your Daily API Request Limit and Monthly API Entitlement.

You can set up email notifications to inform you when your API usage has exceeded specific thresholds to help you monitor your usage against your limits (we’ll discuss this below.) If you are frequently exceeding your Daily API Request Limit, then you need to purchase additional API calls.

We also track your API usage over the previous 30 days, including overages exceeding your Daily API Request Limit. This allows you to monitor your API usage over a longer time period, smoothing out spikes and troughs in daily API usage, and track it against your Monthly API Entitlement. If your monthly API usage is exceeding your Monthly API Entitlement, then you need to purchase additional API calls.

Prior to deploying a new big integration or another event that will lead to many more API calls, proactively plan with the project team or SI partner to factor in these additional calls to your Daily API Request limit to avoid calling Salesforce Support in a last-minute crisis. Also, work with your account team to forecast future traffic and ensure that you have the limit in place to meet your needs.

If your API calls are increasing and you need to raise your Daily API Request Limit, then work with your account team to purchase additional API calls. In addition, using the My Account app in your org, you can purchase the Additional API Calls - 10,000 per day SKU to increase your Daily API Limit.

Checking limits and consumption

There are four ways you can check your API usage relative to your limits.

1) Setup → Company Information page

You can view your daily API usage and monthly API usage in the Company Information page in Setup.

• The daily API usage is in the Organization Detail section, listed as API Requests, Last 24. It indicates your org’s API usage over the preceding 24 hours with the Daily API Request Limit in parenthesis.

The monthly API usage is in the Usage-based Entitlements section, listed as API Request Limit per Month. It shows both your org’s entitlement and usage over the preceding 30 days.

2) Setup → System Overview page

You can view your daily API usage in the System Overview page in Setup. It indicates your org’s API usage over the preceding 24 hours and as a percentage of your Daily API Request Limit.

Limits Info header in API responses

The Limits Info header returned in responses in both the REST API and SOAP API provides API usage information — the number of API calls made in the previous 24 hours and the Daily API Request Limit.

Limits Info header returned in REST API responses:

Limits Info header returned in SOAP API responses:

REST API Limits resource

The REST API Limits resource returns the maximum and remaining allocation for multiple limits in your orgs. You invoke it using:

https://<my-domain>.my.salesforce.com/services/data/vXX.0/limits

The response will include your DailyAPI Request limit — both the maximum API calls and the remaining API calls available in a 24-hour period.

API Usage notifications

You can define API Usage notifications in your org to monitor your API usage against your API limits. An email notification will be sent when your org exceeds a specified threshold, as a percentage of the Daily API Request Limit, within a specified time period.

Below are three API Usage notifications.

1. A notification that is sent every 24 hours if the 50% threshold is reached in the previous 24 hours.
2. A notification that is sent every hour if the 90% threshold is reached in the previous hour.
3. A notification that is sent every four hours if the 80% threshold is reached in the previous four hours.

Viewing API requests

Up to this point, we have been describing how you can monitor your overall API usage against your Daily API Request Limit and Monthly API Entitlement. You may also need insight into individual API requests. For example, you may want to troubleshoot problem requests that require remediating action, or identify requests using deprecated API versions so they can be upgraded to the latest version.

Review API requests with event logs

You can view individual API requests to your org using the API Total Usage events that report SOAP, REST, and Bulk API requests to your org. All orgs can view the daily API Total Usage event log files for the previous 24 hours.

Use the Event Log File Browser to browse the API Total Usage event log files on your org and download them as CSV files to view the individual API events. You can access the event log data in a couple of simple steps.

From within Setup, navigate to Security → Event Monitoring → Event Log Browser.

You can then download the individual event log files as CSV files to view the API events in them.

To identify the client app that made API calls, use the following key fields in the event log data:

• CONNECTED_APP_ID indicates the connected app or external client app that made the API call.
  • If the ID is prefixed with a 4H0, then the ID refers to a connected app
  • If the ID is prefixed with a 888, then the ID refers to an external client app
• CLIENT_NAME is an optional header populated by clients to help identify the calling application.
• USER_ID identifies the user in your org that is used to authenticated the API calls. While this can be helpful in identifying the originating client, be aware that the same system user account might be shared by multiple clients.
• CLIENT_IP is the IP address of the requesting client, but be careful if multiple clients from the same physical location share the same IP address.

You can also access the event log data via the API, and this is well described in the blog post An Important Update to Our Legacy API Retirement Plan.

Greater insights into API requests with Event Monitoring

If you have activated Event Monitoring, then you have access to all the event monitoring event types, including these additional API events:

• Apex REST API events
• Apex SOAP events
• Bulk API events
• Bulk API Request events
• Bulk API 2.0 events
• REST API events
• SOAP API events

In addition, you can view both hourly and daily event log files for up to one year. These additional capabilities enable you to get greater insight into API requests with additional details, both faster and over a longer historical time period.

The image below shows the Event Log File Browser displaying the event logs for many event types, including three API event logs: API Total Usage, REST API, and Bulk API 2.0.

Each API request is assigned a unique request id, and this is included in the API events types in the REQUEST_ID field. A single API call will generate multiple API events — for example, a REST API call will result in both a Total API Usage event and a REST API event. While there are some common fields between the events, different events do contain different information. The REQUEST_ID field enables you to correlate different API event types for the same API request.

The two images below show excerpts from the API Total Usage and REST API event log files. You can use the REQUEST_ID fields in each event log to correlate the events for the same API request.

Best practices to make it easier to identify who made API calls

Being able to identify the applications making API calls to your org is just good API governance. The following best practices can help you identify these calling applications.

Use connected apps or external client apps

The best way to be able to identify the source of API calls is by using connected apps or external client apps as this creates an explicit identity for each client application in your org. The unique ID for the connected app is logged with all API calls made by that application, making identification straightforward.

Specify a client name in all your API calls

Ensure that your client applications specify the client name in the Sforce-Call-Options request header in their API calls. This is an optional header value that can be populated with any text and is logged with all API calls made by that application to help identify it. This header value can be populated in API calls using the REST API, the SOAP API, and the Bulk API.

Create a dedicated user per integration with the Salesforce Integration user license

Salesforce recommends that each application connecting with your org has its own dedicated user. This allows you to only authorize each application to access the data and operations that it needs, and nothing more, while providing distinct auditability and traceability of requests from each application. The user ID of that user is logged with API calls from the application, providing another means to identify the origination.

Salesforce introduced the Salesforce Integration user license as a cost effective means for each application to have its own dedicated user. Read this blog post to learn how to configure the Salesforce Integration user license.

Conclusion

Monitoring your org’s API use is an important operation in the smooth running of your org. This post has described the tools available to you to monitor your org’s API usage, track that usage against your API limits, and gain insights into individual API requests.

Further Resources

• Blog: Accessing Object Data with Salesforce Platform APIs.
• Documentation: API Request Limits and Allocations
• Documentation: Give Integration Users API Only Access
• Blog post: Invoke REST APIs with the Salesforce Integration User and OAuth Client Credentials
• Trailhead: Design Solutions with Salesforce APIs
• Trailhead: Event Monitoring

About the author

Jeremy Westerman is the Director of Product Management for Salesforce APIs. He is responsible for Salesforce APIs that access data on the core Salesforce Platform. You can find him on LinkedIn.