API Reference / REST API / Usage REST API

Usage REST API

The Usage API is only available on Premium plans and plans including our Enterprise add-on.

Overview

The Usage API lets your interact directly with the usages of your Algolia clusters from anything that can send an HTTP request. It helps you see the inner workings of your clusters/replicas, which you can’t do with the API clients.

All API calls transit via HTTPS, via the https://usage.algolia.com domain. APPLICATION_ID variable can be found in your dashboard. API_KEY variable can be found in your 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 section of the Monitoring API is now deprecated, and we encourage all our users to migrate to the new Usage API. While we always do our best to keep our API backwards-compatible, there are changes you must take into account:

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=2020-07-14T13:00:00Z&endDate=2020-07-15T12:00:00Z&granularity=hourly""

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}/period/{period}

Get usage

GET

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

Get usage for an index

Get usage

Path: /1/usage/{statistic}/period/{period}
HTTP Verb: GET

Description:

This method gets a statistic over a period of time

Parameters:

period
type: string
Required

Possible values:

  • day: 1 day ago, 1 point per 1 hour (24 points)
  • month: 1 month ago (30 days), 1 point per day (30 points)
  • year: 1 year ago (365 days), 1 point per day (365 points)
statistic
type: string
Required

Possible values:

To avoid unnecessary extra calls, you may want to request all or part 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
  • 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
  • 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
  • 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 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_search_requests: Sum of all Search API 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 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_search_requests: Sum of all Search API requests
  • 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)

Maximum QPS (query per second)

  • max_qps: Maximum number of query per second over the period (per server)
  • region_max_qps: Maximum number of query per second over the period (per region)
  • total_max_qps: Maximum number of query 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

You use the degraded_queries_* methods to monitor the impact on queries when the server is overloaded. For some methods, we speak of “seconds impacted”. This refers to the percentage of seconds, for a given period, that were affected by a particular degradation. 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.

  • 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 get information on degraded queries by making the following call to the REST API. In this example, we retrieve all degraded queries from the last 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/degraded_queries_*/period/day"

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:

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/period/day"

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

Path: /1/usage/{statistic}/period/{period}/{index}
HTTP Verb: GET

Description:

This method gets a statistic for a given index over a period of time

Parameters:

period
type: string
Required

Possible values:

  • day: 1 day ago, 1 point per 1 hour (24 points)
  • month: 1 month ago (30 days), 1 point per day (30 points)
  • year: 1 year ago (365 days), 1 point per day (365 points)
index
type: string
Required

Index name

statistic
type: string
Required

Possible values:

To avoid unnecessary extra calls, you may want to request all or part 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
  • 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
  • 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_search_requests: Sum of all Search API 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 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_search_requests: Sum of all Search API requests
  • 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:

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,avg_processing_time/period/day/users"

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
1
2
3
4
5
6
7
8
9
10
11
12
{
  "records": [
    {"t": 1455451200000, "v": 53863464},
    {"t": 1455454800000, "v": 53897109},
    ...
  ],
  "avg_processing_time": [
    {"t": 1455451200000, "v": 2},
    {"t": 1455454800000, "v": 3},
    ...
  ]
}

Did you find this page helpful?