API Call Statistics
Cortex paces its requests to some data sources so that a vendor's rate limit is not exceeded.
When performing some actions, such as data migrations, Cortex Admins may have the question of "how many API calls did we actually send in the last minute/hour/day?" The API Statistics tab records every call Cortex issues to a data source, so you can see the real request volume and compare it against the limit the vendor documents. This is helpful for determining if the API rate limit for a particular data source is the performance bottleneck with sending data to that system, or if it is bound by something else (for example, source data source / database performance).
Calls are counted whether or not rate limiting is configured inside Cortex, so you can measure the volume a data source produces before deciding what limits to set.
For a data source whose vendor reports how much of a rate-limit window is left, the same tab can also read the live limits back from the vendor - see Checking a vendor's live rate limits.
Where to see it
On a data source - go to Admin → Data Sources, edit the data source, and select the API Statistics tab.
On a background task - go to Admin → Background Tasks, open a Migrate Data job, and select the API Statistics tab. A migration can read from one data source and write to another, so the tab shows a panel per data source involved, headed Source data source and Target data source. If the task has neither configured, the tab says so instead.
The tab is offered for the data source types Cortex paces through its shared rate limiter - the Platform data source and FreshService. Other types do not issue their calls through that path, so they do not report statistics. You also need permission to view the data source; without it the panel tells you the statistics are not shown rather than displaying numbers.
What the numbers mean
| Value | What it shows |
|---|---|
| Total API calls | Every call recorded since this Cortex instance started. |
| Last minute, Last hour, Last 24 hours | Calls recorded inside that window. |
| Last call | When the most recent call was recorded, in UTC. |
| Per-minute grid | Minute-by-minute counts for the most recent 60 minutes, with the newest minute first. Minutes that carried no traffic are left out, so an idle data source shows "No API calls recorded in the last hour." |
Select Refresh to read the counters again - the panel is a snapshot of the moment it was loaded and does not update on its own.
Things to know
- The counts live in memory only. They are not written to the Cortex database, and they are counted per Cortex instance, so they reset when the application restarts - an IIS restart or an application pool recycle starts the totals again from zero.
- Recent detail is trimmed; the total is not. Per-second detail is discarded after 25 hours, while the lifetime total keeps counting until the next restart.
- One read is not always one call. Some reads are counted per record rather than per query, so a read that returns 100 records from a data source paced per record counts as 100 calls.
- Every caller counts. Calls are recorded where Cortex applies rate limiting, so browsing, background jobs and any other surface that reads the data source all contribute to the same totals.
Checking a vendor's live rate limits
Some vendors tell you how much of a rate-limit window is left on every response Cortex receives, and Cortex can read those figures back for you. Where a data source supports it, the API Statistics tab shows a Vendor API rate limits section with a Check API rate limits button.
Selecting it issues one real request per operation Cortex uses against that instance, and reports what the vendor returned:
| Column | What it shows |
|---|---|
| Rate limit type | The operation the row describes - the overall (account) limit, or an individual operation such as List All Tickets, View Ticket, Create Ticket, Update Ticket, List All Assets, Update Asset, List All Agents or List All Requesters. |
| Limit / window | The limit the vendor applied to that operation. |
| Remaining | How much of the window was unspent when the response arrived. |
| Resets (UTC) | When the window resets, in UTC. |
Beneath the table, the panel explains the result: each row is the limit the vendor applied to that operation's own request, a probe that returned no quota is called out by name, and an operation the server reported as exhausted (or asked you to wait on with Retry-After) is named.
Things worth knowing before you press the button:
- The check costs calls. Every probe is a real request, paced through the data source's configured rate limiting and counted in the statistics above, so a check consumes the quota it reports.
- The write probes are safe. They send a body the API rejects, so they cannot create or change anything; the vendor documents that even a rejected request counts against the limit and still returns the headers.
- It is not one account-wide number. Some vendors enforce an overall account limit plus lower per-operation sub-limits, so each row is the limit for that one operation and the overall row governs everything not listed.
- Nothing is cached. The table shows the instant the check ran; press the button again to read the windows afresh.
If the server returns no rate-limit information at all, the panel says so rather than showing an empty table.
Setting the limit itself
The limit is configured on the Rate Limiting tab, next to API Statistics in the same data source editor. Adding at least one request window turns limiting on, and the combined volume from all callers is then paced to stay inside the configured windows - when more than one window is set, the most restrictive one applies at any moment. API Statistics is the other half of the same picture: it shows whether the traffic you are seeing is close to the limit you configured, or well inside it.
See also
- Data Sources - connecting and configuring source systems