Exploring IBM API Connect v12.1.0 API Analytics with the API Agent's Analytics MCP Tool
by Michael J. O'Sullivan
Introduction
IBM API Connect Version 12.1.0 introduces new AI-enabled Tools for use with the API Agent. One of these Tools is the Analytics Tool – an MCP Tool that allows users to explore, introspect, and visualise runtime analytics data for published APIs using natural language, right from the chat interface of API Agent. This Tool uses some of the existing Dashboard APIs available from the powerful Analytics subsystem of IBM API Connect as a source, which specifically allows the API Agent to answer natural language questions about the runtime behaviour and performance across the landscape of your published APIs.
As of Version 12.1.0 of IBM API Connect, in addition to the existing Microsoft Visual Studio Code plugin (vscode-plugin) for the API Agent, the API Agent chat interface is now also available embedded within both the API Manager User Interface, and the new API Studio, allowing this new Analytics Tool and others to be used with API Agent in a variety of different locations. It is also available as part of the new IBM APIC MCP Server, so that other external MCP Clients are also able to use the Tool.
Capabilities
The Analytics Tool today comprises four operations:
- Get Analytics Latency: Retrieves information on how long API responses take. Useful for finding which APIs take the longest and fastest to respond, how response times have changed over time, and to find the minimum, maximum, and average response times for APIs. This operation uses the Analytics Latency Dashboard.
- Get Analytics Status: Retrieves critical information on API call successes and failures, showing both success and failure rates over time along with an HTTP response code breakdown. This operation uses the Analytics Status Dashboard.
- Get Analytics Usage: Retrieves information on which APIs are being called and which ones aren't. Useful for answering questions about API usage, API popularity, and spikes in API usage. This operation uses the Analytics API Dashboard
- Get Analytics Users: Retrieves information on clients calling APIs. Useful for finding who is calling your APIs, and from what devices (user-agents) and countries the calls are being made. Note: Only internet accessible IP addresses can be resolved to a geographical location. Internal IP addresses are ignored. The GeoIP database is refreshed in each APIC fixpack, as time passes this data might become inaccurate. Apply the latest APIC fixpack to update the GeoIP database. This operation uses the Analytics Client Dashboard.
Let’s walk-through each of these, and use them to demonstrate the features available.
Walk-through with IBM API Connect’s API Agent
In this Blog, I will use the new AI side-panel from the API Manager User Interface/API Studio. As noted in the introduction though, I could also use the Analytics Tool from the vscode-plugin, and the experience and capabilities are exactly the same.
Starting simply, let’s try and find out what is the average response time of all my published APIs in a specific API Connect Catalog, named “api-connect-catalog-1”. I’ll start a new chat with the API Agent within the AI side-panel, and prompt with “What is the average response time of my apis in the api-connect-catalog-1 catalog?”
The API Agent has produced a Plan, and when I look at it in detail, it has identified the Analytics Tool, and selected the “Get Analytics Latency” operation. Let’s execute the Plan.
That was very handy! It has quickly been able to tell me the answer to my question – the average response time of all my APIs published in this Catalog is around 800 milliseconds.
Of course, that just surveyed all of my published APIs in that Catalog, regardless of the kind of response. All of the Analytics Tool operations support the query properties described in the appendix at the bottom of this Blog. We didn’t ask for any before, but to demonstrate, let’s now re-prompt and refine our question to get a more fair assessment. This time I’ll prompt with “What is the average response time of successful calls for my apis in that catalog?” (Note: I did not give the Catalog name again – it was re-populated in the new Plan from the chat history).
niv
Looking at the Plan, this time the Agent has placed a query parameter into the “query” property – “status_code=success”. This will filter the Analytics data to only API calls that responded with a non-error HTTP response code. That’s much better – let’s run that plan.
This time, disregarding API calls with error responses, I see the average response time for successful API calls to my APIs is around 808 milliseconds.
Moving on, let’s find out what exactly those successful HTTP responses being returned are. This time, I’ll prompt with “What are the successful status codes for my apis in that catalog? Show me a pie chart of the data” This time, I’m also asking for a Pie Chart representation of the data – this will hopefully give me a nice visual breakdown of what the response codes being returned.
Looking at the Plan for this prompt, this time the API Agent has chosen the “Get Analytics Status” operation. Once again, the API Agent has populated the query input with “status_code=success”. I can also see the “chart” property has also been set to “pie”, like I requested. Let’s execute the Plan.
Very handy! The textual chat response from the API Agent tells me that the successful response codes are HTTP 200, 201, and 204. Even nicer though, the API Agent had produced a Pie Chart, showing the percentage breakdown of these responses! The chart is dynamic – for example, I can click on the labels to zoom in on the data items I am interested in. As you ca see, it also gives me the option to export the data as an image or text file, and I can see the individual data values in tabular form:
This is all made possible by the use of Carbon Charts. The Charts are rendered in the chat window as an MCP UI Resource, using MCP UI (https://mcpui.dev). For more information on how the visualization of how analytics data is charted for the API Agent, a Blog article dedicated to this topic from my IBM colleague Nivedhitha K can be found at https://community.ibm.com/community/user/blogs/nivedhitha-k/2025/12/30/when-api-agent-starts-drawing.
Now, let us use the Tooling to find out where these successful calls to my APIs are originating from around the globe. Let’s prompt with “What countries made the most calls with successful responses to my rest type apis in the last 2 weeks in that catalog?” This time, in addition to the successful status criteria, we are introducing two additional criteria to be used as query parameters. First, I have said to narrow the data to that for RESTful type APIs only. Secondly, I have given a relative time window to filter the data to the previous 2 weeks only, starting from today (all relative times start from the current datetime). Let’s see what Plan the API Agent produces for this.
As we can see, this time the API Agent has chosen the “Get Analytics Users” operation. The query property now has two key-value pairs; “status_code=successful” as before, but now also “api_type=rest”. Additionally, we can see “dateNum” is set to “2”, while “dateCategory” is set to “week”. Both of these are exactly as we requested. Note that if we had not specified a relative time range or period in our prompt, the Analytics Tool always defaults to the last 7 days. “dateCategory” supports “day”, “week”, “month”, and “quarter” (for 4-months). Finally, this Tool operation has a distinct property of its own called “operation”; it’s set to “top_countries”, which is a data field that the Analytics Client Dashboard contains in its response payload, which contains geographic data of where API calls originate from.
Running this plan, we can see in the chat response that the top three countries calling our RESTful APIs successfully in the last 2-weeks were the United States of America, China, and Japan.
Finally, let’s take a wider view across all the APIs in the Catalog, and use the Tool to understand exactly which of our APIs are being called. Let’s prompt with “What were the most popular restful type apis with successful calls in that catalog between december 10th and december 17th ? show the data in a chart”. Note that I could have used a relative time range here as well, but this is just to demonstrate that explicitly specifying a time period is supported as well.
Looking at the Plan that the API Agent has put together, this time it has chosen the “Get Analytics Usage” operation, which allows users to view analytics data from the perspective of individual published APIs. We see the same query property key-value pairs as before, which is correct. This time around, we can see that “dateNum” and “dateCategory” has been left unset, but alternatively, “startDate”, and “endDate” have now been set appropriately for the start and end dates that I requested (as an aside, explicit times are also supported if requested). Finally, the charts parameter is set to “yes” – this signals that I want a chart, but I have not requested a specific type, which is correct. In this case, the API Agent will try and select a suitable chart type for the data on its own. Finally, this Tool operation also has a distinct property of its own called “operation”; it’s set to “top_apis_by_calls”, which is one of the available data fields in the Analytics API Dashboard response payload, giving a breakdown of APIs based on how many calls they have received – just what we need. Let’s start the Plan.
Impressive, we can now see the individual APIs in this Catalog that match our criteria, both in text form and visualised as a bar chart. By far the most-called API is the “cs-api” API with 977 calls in the requested time period.
With this, we’ve had a glance across the available operations of the Analytics Tool, and the features supported for filtering and visualising the data.
Triaging Runtime Issues with Analytics Data using IBM API Connect’s API Agent
One of the most useful aspects of evaluating analytics data is that it can help to triage and diagnose runtime issues or performance problems with published APIs. Using the various available operations and capabilities we have previous explored, let’s now take a look at a real scenario where the Analytics Tool can assist with this challenge.
Starting a new API Agent chat, let’s have a look at our popular APIs once again, with the prompt “What were the top 5 apis in the last 10 days in the api-connect-catalog-1 catalog? Show a chart”
As before, the “Get Analytics Usage” operation was chosen, and we can see from the results that the “cs-api” is our most-called API in the last 10 days, with 2030 calls. Let’s interrogate this in more detail to see how this is performing in production, and identify any problems. Let’s prompt with “How many error calls were made to the cs-api in that catalog in the same period?” Once again, I am not specifying the name of the catalog again, or the time period, as that information is already in the chat history from my first prompt in this chat session.
The data shows that there have been a variety of different HTTP error-type status code responses in this period. Most of them are client-side error responses – a HTTP 429 Too Many Requests response being the most common with 283 calls. This is interesting because a HTTP 429 response indicates that a client is trying to call this particular more often that we permit. In some circumstances, that could be a symptom of a denial-of-service attack, or a client program misbehaving. Additionally, the next most common error response is HTTP 500 Internal Server Error, with 188 calls. This is a concern because a 50x HTTP status code is a server-side error, and could indicate an issue in our application code not working properly, or is encountering some unhandled exception. I really don’t want my application to return HTTP 50x errors under any circumstances that I can anticipate, as good practice.
I would like to explore these errors in more detail. First, I would like to understand how quickly the server is handling these error cases, as I would like my applications to fail quickly for issues such as HTTP 400 Bad Request responses, where clients have made invalid requests, or sent invalid data. I’ll prompt with “What was the average response time for the 40x response errors. Then, tell me what was the average response time for the 50x response errors”. Using 40x and 50x allows the Analytics API in this case to answer based on the data of all response codes starting with 40 and 50 respectively. Also note that this time I have not specified the name of the cs-api API in my prompt, as again it is already in the chat history.
This time, the API Agent has produced a multi-step plan, both using the “Get Analytics Latency” operation. In both cases, it has remembered the name of the API to query from the chat history. The first step will query for the HTTP 40x error responses average time, while the second step will do the same for the HTTP 50x error responses.
Just what I was looking for – the average response time was 1000 milliseconds for the HTTP 40x responses, and 1500 milliseconds for the HTTP 50x response calls. I would hope for faster responses for the API calls that return 40x, so that is something I will have to look into in my implementation.
Now – lets introspect the API calls resulting in HTTP 40x status codes further. I want to try and determine where these API calls are originating from. Let’s now prompt with “What country called this api the most that resulted in the 40x status responses?
The “Get Analytics Users” operation was chosen. As before, the “operation” property in the Plan is set to “top_countries”. This looks to be exactly what I want.
The result is that most of the API calls that result in a HTTP 40x status code originate in the United States of America. The Analytics subsystem can correlate IP addresses to their geographic origin based on the latest geographic mapping database contained in each specific version of IBM API Connect. Let’s see can we find out exactly what these client IP addresses are. This time, I’ll prompt with “What client ips called this api the most that resulted in the 40x status responses? Show a chart”. We get a plan for the same Analytics Tool operation as before, but this time, the “operation” property of the Plan is set to “top_client_ips_errors_over_time”, which is another data field in the Analytics Client Dashboard response payload, giving a break down over time of the client IP addresses that have called our APIs, that resulted in error status code responses.
The response here has given me the top 3 client IP addresses that made the API calls resulting in these error response HTTP 40x-family status codes – also presented as a simple bar chart this time. I can see that client with IP address 21.21.239.70 made the most error calls, with 4 errors.
Given that the numbers are very small even for the top 3 client IP addresses shown here, and most originate from the United States, it appears that the errors are genuine, and probably down to caller-error, rather than suspicious behavior.
The final diagnosis I would like to verify is for the HTTP 50x family errors. For this, let’s see if the erroring API calls are coming from a particular type of client device, that may trigger some issue with our backend server. For this, I will prompt with “What types of client device called this api the most that resulted in 50x error responses?”.
Once again, the API Agent has correct chosen the same operation of the Analytics Tool as before. Once again though, the “operation” property in the Plan is set to “top_useragents” this time, which is yet another data field in the Analytics Client Dashboard response payload, giving a breakdown of the types of client (i.e. user agents), such as web browsers or programs, making API calls. Looking at the response, the most common client that is calling the cs-api and resulting in the HTTP 50x status error response are coming from an Apache HttpClient, an extremely popular Java library for making HTTP requests from Java application code. This indicates that the calls triggering the HTTP 50x responses are being made programmatically, rather than by an end-user in a web browser. I should investigate what known clients written in Java are calling my APIs, and also I can look at my application server logs for this type of user-agent to help debug further on what the cause of these errors may be.
Using the Analytics Tooling from the IBM APIC MCP Server
The Analytics Tool and its operations that I have demonstrated in this Blog are not only available to IBM API Connect’s API Agent, but can also be used from other MCP Clients that support streamable HTTP transport for streaming data responses, such as GitHub CoPilot for Microsoft Visual Studio Code, Anthropic Claude Desktop, and LangFlow. Once you have setup the IBM APIC MCP Server, and configured your chosen MCP Client to integrate with it, the Analytics Tool becomes available to that MCP Client. For example, see the below screenshot of one of the prompts being entered into Claude Desktop, and the response being shown in a chat:
One important differentiator between using the Analytics Tool with the IBM API Connect’s API Agent versus an external MCP Client like Claude Desktop as shown above, is that the showing of Carbon Charts is not supported in the chat experiences of these external clients. Our Carbon Charts are returned as MCP UI Resources, now supported by the API Agent, but not yet widely supported for other MCP Client applications. Generally speaking, these other MCP Client applications and the LLMs they use are generally already capable of generating their own visualisations of data when you prompt it to do so.
For more information on the IBM APIC MCP Server, and the other Tools it supports, see the GitHub repository at https://github.com/ibm-apiconnect/apic-mcp-server. Additionally, a Blog article on this is coming soon.
Conclusions
In this Blog, I introduced you to the new Analytics Tool – a new MCP Tool introduced as part of the API Agent in the version 12.1.0 release of IBM API Connect, and also available as part of the IBM APIC MCP Server. I have taken you on a walkthrough of the capabilities you can leverage with the different operations available for this Tool, and also shown you how it can be useful to perform some triaging and investigation of runtime performance and issues with published APIs in IBM API Connect, based on the available data from the Analytics Subsystem.
For more information of all the supported Operations of the Analytics Tool, including the definitive list of supported Plan properties, chart types, and example prompts, see the IBM documentation site page for this Tool at https://www.ibm.com/docs/en/api-connect/software/12.1.0?topic=tools-analytics
Remember: Before taking making any decisions or taking any actions based on Analytics Tool output from the API Agent, recall that LLMs can hallucinate. When making decisions or planning to take actions based on the API Agent's answers to questions regarding analytics data, always verify responses against the analytics data in IBM API Connect, such as by studying the Analytics Dashboards available in the API Manager User Interface.
Acknowledgements
I wish to acknowledge and thank my IBM colleagues Nivedhitha K, Sony Vayalil, and Darragh Condron, all of whom significantly contributed to the content demonstrated in this Blog.
References and Links
Appendix
Supported Analytics Query Parameters (all optional):
- status_code: Filter by response status. Valid values: "20x", "40x", "50x", "success", "error" (only one value allowed)
- method: Filter by HTTP method. Valid values: "GET", "PUT", "POST", "DELETE", "HEAD", "TRACE", "OPTIONS" (only one value allowed)
- api_name: Filter by API name. Can be any string matching an API name (only one value allowed)
- api_type: Filter by API type. Valid values: "rest", "graphql", "wsdl" (only one value allowed)
- consumer_org_name: Filter by Consumer Organization name. Can be any string matching an IBM API Connect Consumer Organization name (only one value allowed).