Algolia DevCon
Oct. 2–3 2024, virtual.
API reference / Usage API

Access to the Usage REST API is available as part of the Premium plan or as the Enterprise add-on to other pricing plans.

The Usage API lets you retrieve various usage statistics regarding all HTTP requests made to your Algolia applications. It helps you see your app’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 it’s version 1 of the API.

Request format

Authentication is done via HTTP headers. The X-Algolia-Application-Id header identifies which app 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 (such as 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. You should migrate to the new Usage API. While Algolia always strives to keep these 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 July 15, 2020 at 12:30 AM 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

Error code 422 is now used 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/{statistic}

Get usage

GET

/1/usage/{statistic}/{index}

Get usage for an index

Get usage

A

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:

  • hourly : 1 point per hour. The maximum time range with this granularity is 7 days.
  • daily: 1 point per day. The maximum time range with this granularity is 365 days.
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

  • browse_operations: number of Browse operations
  • clear_index_operations: number of Clear Index operations
  • copy_move_operations: number of Copy or Move Index operations
  • delete_index_operations: number of Delete Index operations
  • get_log_operations: number of Get Logs operations
  • get_settings_operations: number of Get Settings operations
  • set_settings_operations: number of Set Settings operations
  • list_indices_operations: number of List Indices operations
  • wait_task_operations: number of Wait Task operations

Record operations

Synonym operations

Rule operations

  • batch_rules_operations: number of Batch Rules operations
  • clear_rules_operations: number of Clear Rules operations
  • delete_rules_operations: number of Delete Rule operations
  • get_rules_operations: number of Get Rule operations
  • save_rules_operations: number of Save Rule operations
  • search_rules_operations: number of Search Rules operations

Total operations

  • total_search_operations: sum of all Search operations metrics
  • total_search_requests: sum of all Search requests. The number of billed search requests is equal to this value minus querysuggestions_total_search_requests
  • total_recommend_requests: sum of all Recommend requests
  • total_acl_operations: sum of all ACL operations metrics
  • total_indexing_operations: sum of all indexing operations metrics
  • total_records_operations: sum of all record operations metrics
  • total_synonym_operations: sum of all synonym operations metrics
  • total_rules_operations: sum of all rule operations metrics
  • total_write_operations: sum of all write operations
  • total_read_operations: sum of all read operations
  • total_operations: sum of all operations

Total Query Suggestions operations

Query Suggestions operations represent a subset of the total search operations. These are all the operations made via the Query Suggestions feature.

  • querysuggestions_total_search_operations: sum of all Query Suggestions Search operations
  • querysuggestions_total_search_requests: sum of all Search requests generated to build up query suggestions
  • querysuggestions_total_acl_operations: sum of all Query Suggestions ACL operations metrics
  • querysuggestions_total_indexing_operations: sum of all Query Suggestions Indexing operations metrics
  • querysuggestions_total_records_operations: sum of all Query Suggestions Record operations metrics
  • querysuggestions_total_synonym_operations: sum of all Query Suggestions Synonym operations metrics
  • querysuggestions_total_rules_operations: sum of all Query Suggestions Rule operations metrics
  • querysuggestions_total_write_operations: sum of all Query Suggestions Write operations
  • querysuggestions_total_read_operations: sum of all Query Suggestions Read operations
  • querysuggestions_total_operations: sum of all Query Suggestions operations

Processing time

  • avg_processing_time: average processing time (in millisecond)
  • 90p_processing_time: 90th percentile of processing time (in millisecond)
  • 99p_processing_time: 99th percentile of processing time (in millisecond)
  • queries_above_last_ms_processing_time: number of queries processed in 1s or more

Indices

  • records: total number of records
  • data_size: total size of all the indices’ records (in byte)
  • file_size: total size of all the indices’ records and metadata (in byte)

Maximum QPS (query per second)

  • max_qps: maximum queries per second over the time range (per server)
  • region_max_qps: maximum queries per second over the time range (per region)
  • total_max_qps: maximum queries per second across all servers

Used search capacity

  • used_search_capacity: max used search capacity in percentage (per server)
  • avg_used_search_capacity: average used search capacity in percentage (per server)
  • region_used_search_capacity: max used search capacity in percentage (per region)
  • region_avg_used_search_capacity: average used search capacity in percentage (per region)
  • total_used_search_capacity: max used search capacity in percentage across all servers
  • total_avg_used_search_capacity: average used search capacity in percentage across all servers

Degraded queries

  • degraded_queries_ssd_used_queries_impacted: percentage of queries that made the Algolia search engine read from the SSD.
  • degraded_queries_ssd_used_seconds_impacted: percentage of seconds impacted by a ssd_used degradation.
  • degraded_queries_max_capacity_queries_impacted: percentage of queries degraded because all threads available for search were used.
  • degraded_queries_max_capacity_seconds_impacted: percentage of seconds impacted by a max_capacity degradation.

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 degraded_queries_max_capacity_seconds_impacted returns 50% for one hour, it means that 1800/3600 were affected by a max_capacity. Note that the impacted seconds may not be contiguous.

Other

  • insights_operations: Number of operations on the Insights API

Grouping

  • *: returns all the Usage metrics in the same response
  • search_operations: returns all Search operations metrics in the same response
  • acl_operations: returns all ACL operations metrics in the same response
  • indexing_operations: returns all Indexing operations metrics in the same response
  • record_operations: returns all Record operations metrics in the same response
  • synonym_operations: returns all Synonym operations metrics in the same response
  • rule_operations: returns all Rule operations metrics in the same response

Example:

A

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 milliseconds
  • v: 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_qps
  • region_*
  • 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

A

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:

  • hourly : 1 point per hour. The maximum time range with this granularity is 7 days.
  • daily: 1 point per day. The maximum time range with this granularity is 365 days.
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

  • queries_operations: Number of single queries
  • multi_queries_operations: Number of multiple queries (queries within batches)

ACL operations

  • get_api_key_operations: Number of Get API Key operations i.e. /1/indexes/:idx/keys/:key
  • get_api_keys_operations: Number of Get API Keys operations i.e. /1/indexes/:idx/keys
  • add_api_key_operations: Number of Add API Key operations
  • update_api_key_operations: Number of Update API Key operations
  • delete_api_key_operations: Number of Delete API Key operations

Indexing operations

  • browse_operations: Number of Browse operations
  • clear_index_operations: Number of Clear Index operations
  • copy_move_operations: Number of Copy or Move Index operations
  • delete_index_operations: Number of Delete Index operations
  • get_log_operations: Number of Get Logs operations
  • get_settings_operations: Number of Get Settings operations
  • list_indices_operations: Number of List Indices operations
  • set_settings_operations: Number of Set Settings operations
  • wait_task_operations: Number of Wait Task operations

Record operations

  • add_record_operations: Number of Add Object operations
  • batch_operations: Number of Batch operations
  • delete_by_query_operations: Number of Delete By Query operations
  • delete_record_operations: Number of Delete Object operations
  • get_record_operations: Number of Get Object operations
  • partial_update_record_operations: Number of Partial Update Object operations
  • update_record_operations: Number of Update Object operations

Synonym operations

  • batch_synonym_operations: Number of Batch Synonyms operations
  • delete_synonym_operations: Number of Delete Synonym operations
  • get_synonym_operations: Number of Get Synonym operations
  • query_synonym_operations: Number of Search Synonym operations
  • update_synonym_operations: Number of Update Synonym operations

Rule operations

  • batch_rules_operations: Number of Batch Rules operations
  • clear_rules_operations: Number of Clear Rules operations
  • delete_rules_operations: Number of Delete Rule operations
  • get_rules_operations: Number of Get Rule operations
  • save_rules_operations: Number of Save Rule operations
  • search_rules_operations: Number of Search Rules operations

Total operations

  • total_search_operations: Sum of all Search operations metrics
  • total_acl_operations: Sum of all ACL operations metrics
  • total_indexing_operations: Sum of all Indexing operations metrics
  • total_records_operations: Sum of all Record operations metrics
  • total_synonym_operations: Sum of all Synonym operations metrics
  • total_rules_operations: Sum of all Rule operations metrics
  • total_write_operations: Sum of all Write metrics
  • total_read_operations: Sum of all Read operations
  • total_operations: Sum of all operations

Total Query Suggestions operations

Query Suggestions operations represent a subset of the total search operations. These are all the operations made via the Query Suggestions feature.

  • querysuggestions_total_search_operations: Sum of all Search operations
  • querysuggestions_total_acl_operations: Sum of all ACL operations metrics
  • querysuggestions_total_indexing_operations: Sum of all Indexing operations metrics
  • querysuggestions_total_records_operations: Sum of all Record operations metrics
  • querysuggestions_total_synonym_operations: Sum of all Synonym operations metrics
  • querysuggestions_total_rules_operations: Sum of all Rule operations metrics
  • querysuggestions_total_write_operations: Sum of all Write metrics
  • querysuggestions_total_read_operations: Sum of all Read operations
  • querysuggestions_total_operations: Sum of all operations

Processing time

  • avg_processing_time: Average processing time (in millisecond)
  • 90p_processing_time: 90th percentile of processing time (in millisecond)
  • 99p_processing_time: 99th percentile of processing time (in millisecond)
  • queries_above_last_ms_processing_time: Number of queries processed in 1s or more

Indices

  • records Total number of records
  • data_size Total size of all the indices’ records (in byte)
  • file_size Total size of all the indices’ records and metadata (in byte)

Grouping

  • *: returns all the Usage metrics in the same response
  • search_operations: returns all Search operations metrics in the same response
  • acl_operations: returns all ACL operations metrics in the same response
  • indexing_operations: returns all Indexing operations metrics in the same response
  • record_operations: returns all Record operations metrics in the same response
  • synonym_operations: returns all Synonym operations metrics in the same response
  • rule_operations: returns all Rule operations metrics in the same response

Example:

A

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 milliseconds
  • v: 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_qps
  • region_*
  • 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}},
    ...
  ]
}
Did you find this page helpful?