Usage API

The Usage API lets you retrieve various usage statistics regarding all HTTP requests made to your Algolia applications.

Access to the Usage REST API is available as part of the Premium plan or as an Enterprise add-on. For more information, see Pricing.

It helps you see your app’s inner workings, in a way you can’t with API clients.

All API calls use HTTPS, with 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.

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 by 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:

{
  "status": 4xx,
  "message": "The error message"
}

Migration 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 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)

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)

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)

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)

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:

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 [...]"
}

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

GET /1/usage/{statistic}

This method gets one or more statistics over a time range.

Parameters

startDate · string · required

The lower bound timestamp (a string like “2006-01-02T00:00:00.000Z”) of the time range to query.

endDate · string · required

The upper bound timestamp (a string like “2006-01-02T23:23:59.999Z”) of the time range to query.

granularity · string · default: "daily"

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 · string · required

The statistics to retrieve. You can 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

• queries_operations: number of single queries
• multi_queries_operations: number of multiple queries (batched queries)

ACL operations

• get_api_key_operations: number of Get API key operations
• get_api_keys_operations: number of Get API keys operations
• 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
• list_api_key_operations: number of List API Keys 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

• 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
• clear_synonym_operations: number of Clear synonyms operations
• delete_synonym_operations: number of Delete synonym operations
• get_synonym_operations: number of Get synonym operations
• query_synonym_operations: number of Search synonyms 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_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 milliseconds)
• 90p_processing_time: 90th percentile of processing time (in milliseconds)
• 99p_processing_time: 99th percentile of processing time (in milliseconds)
• queries_above_last_ms_processing_time: number of queries processed in 1 second 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 queries 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 out of 3600 seconds were affected by a max_capacity. The impacted seconds need not be contiguous.

Other

• insights_operations: number of operations on the Insights API

Grouping

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

Example:

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, the value type might differ. Most metrics are integers, except:

• degraded_queries_*
• max_qps
• region_*
• used_search_capacity

These metrics are key-value pairs with server or region names as keys and the metric as integer values.

JSON

{
  "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

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

This method gets one or more statistics for a given index over a time range.

Parameters

startDate · string · required

The lower bound timestamp (a string like “2006-01-02T00:00:00.000Z”) of the time range to query.

endDate · string · required

The upper bound timestamp (a string like “2006-01-02T23:23:59.999Z”) of the time range to query.

granularity · string · default: "daily"

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 · string · required

Index name

statistic · string · required

The statistics to retrieve. You can 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.

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 milliseconds)
• 90p_processing_time: 90 th percentile of processing time (in milliseconds)
• 99p_processing_time: 99 th percentile of processing time (in milliseconds)
• queries_above_last_ms_processing_time: number of queries processed in 1 second 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

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

Example:

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, the value type might differ. Most metrics are integers, except:

• degraded_queries_*
• max_qps
• region_*
• used_search_capacity

These metrics are key-value pairs with server or region names as keys and the metric as integer values.

JSON

{
  "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}},
    // ...
  ]
}