API Call Volume History and Usage Health
Evaluate and optimize your API requests by using the API Call Volume History and Usage Health report. The report includes the API call volumes and success rates for your Marketing Cloud Engagement account.
To get this report, contact your account executive. The report is available as a PDF or CSV file.
The API Call Volume History and Usage Health report includes metrics related to inbound SOAP and REST API requests made to Marketing Cloud Engagement from other applications. The report counts a batched API request as an individual request.
The report also includes metrics for outbound Journey Builder custom API requests. It doesn’t count other types of outbound API requests, such as Event Notification Service requests or HTTPS postbacks for asynchronous SOAP API requests.
The report also doesn’t count API requests that initiate message sends on the email, SMS, and push channels. Message sends for these channels count as super messages. See your monthly super message usage report.
The API Call Volume History and Usage Health report includes these fields.
Field | Description |
---|---|
Protocol | The API type associated with the request. For inbound requests, the value can be either SOAP or REST . Outbound requests are identified as Outbound , regardless of whether the API that receives the request is a SOAP or REST API. |
Client ID | The client ID that was used to authenticate the request. This field is populated only for REST API requests that were authenticated using OAuth2. For all inbound SOAP API requests and outbound requests, the value of this field is N/A . |
API | The feature or service that the API request invoked. For REST requests, this field maps to the API service listed in the URL. For example, in the URL {subdomain}.auth.marketingcloudapis.com/hub/v1/rest , the value of the API field is hub . For SOAP requests, this field maps to a SOAP object type. The value of this field is Other for SOAP API requests that contain no objects, requests that contain a batch of mixed object types, and requests that fail to authenticate. For example, GetSystemStatus requests or requests to describe a subscriber have no objects, so the result is a value of Other in this field. |
Route or Object | For REST API requests, this field contains the endpoint URL of the request. For SOAP API requests, this field contains the name of the object that the request invoked. |
Method | For REST API requests, this field contains the HTTP verb that's associated with the request, such as GET or POST . For SOAP API requests, this field contains the web service API method for the request, such as Create or Update . |
Last Month Volume | The number of requests for the API during the most recent full calendar month. |
Last Month Success Rate | The percentage of requests that were completed successfully during the most recent full calendar month. The success rate is calculated by dividing the number of successful requests by the total number of requests. |
Peak Month Volume | The number of requests during the full calendar month that had the highest total volume of requests. |
Overall Volume | The total number of API requests over the specified time period. The time period can contain data from the most recent 24 calendar months. The report is sorted in descending order based on the values in this column. |
Whether a request counts as a success or failure depends on the response that the API returns.
This table shows which SOAP API responses count as successes and which count as failures.
API Response | Status Used in Success Rate | Description |
---|---|---|
OK | Success | All objects in the request were processed. |
HasErrors | Success | Some objects in the request failed, but at least one object was processed. |
MoreDataAvailable | Success | Additional pages of data can be retrieved. Returned only on a Retrieve request. |
Error | Error | None of the objects in the request were processed. |
For REST requests, whether a request counts as a success or failure depends on the HTTP status code the API returns. This table shows which HTTP status codes count as successes and which count as failures.
API Response | Status Used in Success Rate | Description |
---|---|---|
HTTP status code 100–199 | Success | These status codes are informational messages. |
HTTP status code 200–299 | Success | These status codes indicate that the request was completed successfully. |
HTTP status code 300–399 | Success | These status codes indicate that the URL of the resource has changed. |
HTTP status code 400–499 | Failure | These status codes indicate a client-side error, such as an incorrectly formatted request, a lack of authorization, or an incorrect resource URL. |
HTTP status code 500–599 | Failure | These status codes indicate a server-side error, such as the temporary or permanent unavailability of a resource. |
Marketing Cloud Engagement doesn’t monitor success or failure responses for external APIs. As a result, all outbound requests count as successes.
Use the API Call Volume History and Usage Health report to improve the overall health of your API usage. For example, use the report to identify API types that have a low success rate. Investigate and resolve errors that occur in these APIs based on the status returned in the API response.
The API Call Volume History and Usage Health report also helps you optimize your API requests so that you don’t exceed the API request limits for your account. Use the report to identify APIs with a high request volume. Next, consider batching objects in each API request to reduce the overall request volume.
You can also use the report to optimize performance. For example, you can replace data extension API requests with data imports for large data extension updates. You can also use list-based sending instead of using the API to issue high-volume triggered sends.