Usage REST API
The Usage API is only available on Premium plans and plans including our Enterprise add-on.
Overview
The Usage API lets you retrieve various usage statistics regarding all HTTP requests made to your Algolia applications. It helps you see your application’s inner workings, in a way you can’t with API clients.
All API calls transit via HTTPS, via the https://usage.algolia.com domain. You can find the APPLICATION_ID variable in your dashboard, and the API_KEY variable on the API Keys page, under the Usage section.
1
2
export APPLICATION_ID="your application id"
export API_KEY="your usage API key"
The relative path prefix /1/ indicates that we are currently using version 1 of the API.
Request Format
Authentication is done via HTTP headers.
The X-Algolia-Application-Id header identifies which application you are accessing, and the X-Algolia-API-Key header authenticates the endpoint.
Response Format
The response format for all requests is a JSON object.
Whether a request succeeded is indicated by the HTTP status code.
A 2xx status code indicates success, whereas a 4xx status code indicates failure.
When a request fails, the response body is still JSON, but contains a message field which you can use for debugging.
Errors
In case of errors (e.g., authentication, validation, or rate limit errors), the API returns a payload in the following format:
1
2
3
4
{
"status": 4xx,
"message": "The error message"
}
Migrating from the Monitoring API
The usage endpoints of the Monitoring API are now deprecated, and we encourage all our users to migrate to the new Usage API. While we always do our best to keep our APIs backwards-compatible, there are some changes you must take into account:
Time range
The Monitoring API relies on the period parameter (as an enum) to derive the time range. With the Usage API, you can use the startDate, endDate, and granularity parameters, which are more flexible.
Here’s a list of period values supported on the Monitoring API and their Usage API equivalents, using startDate, endDate, and granularity (assuming that NOW() is the July 15th, 2020 at 12:30 a.m. UTC).
last_day (last day with one data point)
1
2
3
4
5
curl -X GET \
-H "X-Algolia-API-Key: ${API_KEY}" \
-H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
--compressed \
"https://usage.algolia.com/1/usage/records?startDate=2020-07-15T00:00:00Z&endDate=2020-07-16T00:00:00Z&granularity=daily"
day (last 24 hours with one data point per hour)
1
2
3
4
5
curl -X GET \
-H "X-Algolia-API-Key: ${API_KEY}" \
-H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
--compressed \
"https://usage.algolia.com/1/usage/records?startDate=2020-07-14T13:00:00Z&endDate=2020-07-15T13:00:00Z&granularity=hourly"
month (last 30 days with one data point per day)
1
2
3
4
5
curl -X GET \
-H "X-Algolia-API-Key: ${API_KEY}" \
-H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
--compressed \
"https://usage.algolia.com/1/usage/records?startDate=2020-06-16T00:00:00Z&endDate=2020-07-16T00:00:00Z&granularity=daily"
year (last 365 days with one data point per day)
1
2
3
4
5
curl -X GET \
-H "X-Algolia-API-Key: ${API_KEY}" \
-H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
--compressed \
"https://usage.algolia.com/1/usage/records?startDate=2019-07-17T00:00:00Z&endDate=2020-07-16T00:00:00Z&granularity=daily"
Error response
We now use the error code 422 instead of 400. While the Monitoring API provides a reason property in case of an error payload, the Usage API returns a message:
1
2
3
4
5
6
7
8
9
10
11
curl -X GET \
-H "X-Algolia-API-Key: ${API_KEY}" \
-H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
--compressed \
"https://status.algolia.com/1/usage/metric_does_not_exist/period/day"
HTTP/2 400
...
{
"reason": "unknown types. Possible values are [...]"
}
1
2
3
4
5
6
7
8
9
10
11
12
curl -X GET \
-H "X-Algolia-API-Key: ${API_KEY}" \
-H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
--compressed \
"https://usage.algolia.com/1/usage/metric_does_not_exist?startDate=${startDate}&endDate=${endDate}"
HTTP/2 422
...
{
"status": 422,
"message": "Metric \"metric_does_not_exist\" not found"
}
Empty response
The empty response [] is now {}. Note that calls which request several metrics now only return metrics that contain data, and omits others.
Usage Endpoints
Quick Reference
| Verb | Path | Method |
|---|---|---|
|
GET |
/1/usage/ |
|
|
GET |
/1/usage/ |
Get usage
Path: /1/usage/{statistic}
HTTP Verb: GET
Description:
This method gets one or more statistics over a time range.
Parameters:
startDate
|
type: Date, UTC. Inclusive.
Required
The lower bound timestamp (a string like “2006-01-02T00:00:00.000Z”) of the time range to query. |
endDate
|
type: Date, UTC. Exclusive.
Required
The upper bound timestamp (a string like “2006-01-02T23:23:59.999Z”) of the time range to query. |
granularity
|
type: hourly | daily
default: daily
Optional
Possible values:
|
statistic
|
type: string
Required
The statistics to retrieve. You may include one or multiple comma-separated values. To avoid unnecessary calls, you can request all or some of the following metrics with the different grouping statistics listed below. Search operations
ACL operations
Indexing operations
Record operations
Synonym operations
Rule operations
Total operations
Total Query Suggestions operationsQuery Suggestions operations represent a subset of the total search operations. These are all the operations made via the Query Suggestions feature.
Processing time
Indices
Maximum QPS (query per second)
Used search capacity
Degraded queries
You can retrieve the degraded_queries_* statistics to monitor the impact of degraded queries when the server is overloaded.
Some statistics provide the “percentage of seconds impacted.” This refers to the percentage of seconds that queries were affected by a particular degradation for a given time range.
For instance, if Other
Grouping
|
Example:
1
2
3
4
5
curl -X GET \
-H "X-Algolia-API-Key: ${API_KEY}" \
-H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
--compressed \
"https://usage.algolia.com/1/usage/records,max_qps,region_max_qps?startDate=${startDate}&endDate=${endDate}"
When the query is successful, the HTTP response is a 200 OK and returns the metrics:
t: Timestamp in millisecondsv: Value of the metric
Depending on the metric kind, the type of the value may differ. The majority of the metrics are integer values except the following ones:
degraded_queries_*max_qpsregion_*used_search_capacity
The values of those metrics are returned as maps of string to integer where
the keys are server names, or regions in the case of region_* metrics.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"records": [
{"t": 1455451200000, "v": 53863464},
{"t": 1455454800000, "v": 53897109},
...
],
"max_qps": [
{"t": 1455451200000, "v": {"c4-fr-1": 35, "c4-fr-2": 40, "c4-fr-3": 37}},
{"t": 1455454800000, "v": {"c4-fr-1": 34, "c4-fr-2": 35, "c4-fr-3": 33}},
...
],
"region_max_qps": [
{"t": 1455451200000, "v": {"eu": 185}},
{"t": 1455454800000, "v": {"eu": 186}},
...
]
}
Get usage for an index
Path: /1/usage/{statistic}/{index}
HTTP Verb: GET
Description:
This method gets one or more statistics for a given index over a time range.
Parameters:
startDate
|
type: Date, UTC. Inclusive.
Required
The lower bound timestamp (a string like “2006-01-02T00:00:00.000Z”) of the time range to query. |
endDate
|
type: Date, UTC. Exclusive.
Required
The upper bound timestamp (a string like “2006-01-02T23:23:59.999Z”) of the time range to query. |
granularity
|
type: hourly | daily
default: daily
Optional
Possible values:
|
index
|
type: string
Required
Index name |
statistic
|
type: string
Required
The statistics to retrieve. You may include one or multiple comma-separated values. Possible values: To avoid unnecessary calls, you may want to request all or some of the following metrics with the different grouping statistics listed below. Search operations
ACL operations
Indexing operations
Record operations
Synonym operations
Rule operations
Total operations
Total Query Suggestions operationsQuery Suggestions operations represent a subset of the total search operations. These are all the operations made via the Query Suggestions feature.
Processing time
Indices
Grouping
|
Example:
1
2
3
4
5
curl -X GET \
-H "X-Algolia-API-Key: ${API_KEY}" \
-H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
--compressed \
"https://usage.algolia.com/1/usage/records,max_qps,region_max_qps/${index}?startDate=${startDate}&endDate=${endDate}"
When the query is successful, the HTTP response is a 200 OK and returns the metrics:
t: Timestamp in millisecondsv: Value of the metric
Depending on the metric kind, the type of the value may differ. The majority of the metrics are integer values except the following ones:
degraded_queries_*max_qpsregion_*used_search_capacity
The values of those metrics are returned as maps of string to integer where
the keys are server names, or regions in the case of region_* metrics.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"records": [
{"t": 1455451200000, "v": 53863464},
{"t": 1455454800000, "v": 53897109},
...
],
"max_qps": [
{"t": 1455451200000, "v": {"c4-fr-1": 35, "c4-fr-2": 40, "c4-fr-3": 37}},
{"t": 1455454800000, "v": {"c4-fr-1": 34, "c4-fr-2": 35, "c4-fr-3": 33}},
...
],
"region_max_qps": [
{"t": 1455451200000, "v": {"eu": 185}},
{"t": 1455454800000, "v": {"eu": 186}},
...
]
}
