> ## Documentation Index > Fetch the complete documentation index at: https://algolia.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://www.algolia.com/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](https://dashboard.algolia.com/account/api-keys), under the Usage section. ```sh Command line icon=square-terminal theme={"system"} export ALGOLIA_APPLICATION_ID="your application id" export ALGOLIA_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: ```json JSON icon=braces theme={"system"} { "status": 4xx, "message": "The error message" } ``` ### Migration from the Monitoring API The `usage` endpoints of the [Monitoring API](/doc/rest-api/monitoring) 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](/doc/rest-api/monitoring) 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](/doc/rest-api/monitoring) 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) ```sh Command line icon=square-terminal theme={"system"} curl -X GET \ -H "X-Algolia-API-Key: $ALGOLIA_API_KEY" \ -H "X-Algolia-Application-Id: $ALGOLIA_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) ```sh Command line icon=square-terminal theme={"system"} curl -X GET \ -H "X-Algolia-API-Key: $ALGOLIA_API_KEY" \ -H "X-Algolia-Application-Id: $ALGOLIA_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) ```sh Command line icon=square-terminal theme={"system"} curl -X GET \ -H "X-Algolia-API-Key: $ALGOLIA_API_KEY" \ -H "X-Algolia-Application-Id: $ALGOLIA_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) ```sh Command line icon=square-terminal theme={"system"} curl -X GET \ -H "X-Algolia-API-Key: $ALGOLIA_API_KEY" \ -H "X-Algolia-Application-Id: $ALGOLIA_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](/doc/rest-api/monitoring) provides a `reason` property in case of an error payload, the Usage API returns a `message`: ```sh Command line icon=square-terminal theme={"system"} curl -X GET \ -H "X-Algolia-API-Key: $ALGOLIA_API_KEY" \ -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \ --compressed \ "https://status.algolia.com/1/usage/metric_does_not_exist/period/day" HTTP/2 400 ... { "reason": "unknown types. Possible values are [...]" } ``` ```sh Command line icon=square-terminal theme={"system"} curl -X GET \ -H "X-Algolia-API-Key: $ALGOLIA_API_KEY" \ -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \ --compressed \ "https://usage.algolia.com/1/usage/metric_does_not_exist?startDate=$START_DATE&endDate=$END_DATE" 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 ### Reference | Verb | Path | Method | | ---- | -------------------------------- | ------------------------------------------------- | | GET | /1/usage/`{statistic}` | [Get usage](#get-usage) | | GET | /1/usage/`{statistic}`/`{index}` | [Get usage for an index](#get-usage-for-an-index) | ### Get usage `GET /1/usage/{statistic}` This method gets one or more statistics over a time range. #### Parameters The lower bound timestamp (a string like "2006-01-02T00:00:00.000Z") of the time range to query. The upper bound timestamp (a string like "2006-01-02T23:23:59.999Z") of the time range to query. 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. 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](#grouping) listed below. **Search operations** * `queries_operations`: number of [single queries](/doc/rest-api/search/search-single-index) * `multi_queries_operations`: number of [multiple queries](/doc/rest-api/search/search) (batched queries) **ACL operations** * `get_api_key_operations`: number of [Get API key](/doc/rest-api/search/get-api-key) operations * `get_api_keys_operations`: number of [Get API keys](/doc/rest-api/search/list-api-keys) operations * `add_api_key_operations`: number of [Add API key](/doc/rest-api/search/add-api-key) operations * `update_api_key_operations`: number of [Update API key](/doc/rest-api/search/update-api-key) operations * `delete_api_key_operations`: number of [Delete API key](/doc/rest-api/search/delete-api-key) operations * `list_api_key_operations`: number of [List API Keys](/doc/rest-api/search/list-api-keys) operations **Indexing operations** * `browse_operations`: number of [Browse](/doc/rest-api/search/browse) operations * `clear_index_operations`: number of [Clear index](/doc/rest-api/search/clear-objects) operations * `copy_move_operations`: number of [Copy or move index](/doc/rest-api/search/operation-index) operations * `delete_index_operations`: number of [Delete index](/doc/rest-api/search/delete-index) operations * `get_log_operations`: number of [Get logs](/doc/rest-api/search/get-logs) operations * `get_settings_operations`: number of [Get settings](/doc/rest-api/search/get-settings) operations * `set_settings_operations`: number of [Set settings](/doc/rest-api/search/set-settings) operations * `list_indices_operations`: number of [List indices](/doc/rest-api/search/list-indices) operations * `wait_task_operations`: number of [Wait task](/doc/rest-api/search/get-task) operations **Record operations** * `add_record_operations`: number of [Add object](/doc/rest-api/search/save-object) operations * `batch_operations`: number of [Batch](/doc/rest-api/search/batch) operations * `delete_by_query_operations`: number of [Delete by query](/doc/rest-api/search/delete-by) operations * `delete_record_operations`: number of [Delete object](/doc/rest-api/search/delete-object) operations * `get_record_operations`: number of [Get object](/doc/rest-api/search/get-object) operations * `partial_update_record_operations`: number of [Partial update object](/doc/rest-api/search/partial-update-object) operations * `update_record_operations`: number of [Update object](/doc/rest-api/search/add-or-update-object) operations **Synonym operations** * `batch_synonym_operations`: number of [Batch synonyms](/doc/rest-api/search/save-synonyms) operations * `clear_synonym_operations`: number of [Clear synonyms](/doc/rest-api/search/clear-synonyms) operations * `delete_synonym_operations`: number of [Delete synonym](/doc/rest-api/search/delete-synonym) operations * `get_synonym_operations`: number of [Get synonym](/doc/rest-api/search/get-synonym) operations * `query_synonym_operations`: number of [Search synonyms](/doc/rest-api/search/search-synonyms) operations * `update_synonym_operations`: number of [Update synonym](/doc/rest-api/search/save-synonym) operations **Rule operations** * `batch_rules_operations`: number of [Batch rules](/doc/rest-api/search/save-rules) operations * `clear_rules_operations`: number of [Clear rules](/doc/rest-api/search/clear-rules) operations * `delete_rules_operations`: number of [Delete rule](/doc/rest-api/search/delete-rule) operations * `get_rules_operations`: number of [Get rule](/doc/rest-api/search/get-rule) operations * `save_rules_operations`: number of [Save rule](/doc/rest-api/search/save-rule) operations * `search_rules_operations`: number of [Search rules](/doc/rest-api/search/search-rules) operations **Total operations** * `total_search_operations`: sum of all [Search operations](#search-operations) metrics * `total_search_requests`: sum of all [Search requests](https://support.algolia.com/hc/en-us/articles/17245378392977) . The number of billed search requests is equal to this value minus querysuggestions\_total\_search\_requests * `total_recommend_requests`: sum of all [Recommend requests](/doc/guides/algolia-recommend/overview) * `total_acl_operations`: sum of all [ACL operations](#acl-operations) metrics * `total_indexing_operations`: sum of all [indexing operations](#indexing-operations) metrics * `total_records_operations`: sum of all [record operations](#record-operations) metrics * `total_synonym_operations`: sum of all [synonym operations](#synonym-operations) metrics * `total_rules_operations`: sum of all [rule operations](#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](/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/js). * `querysuggestions_total_search_operations`: sum of all Query Suggestions [search operations](#search-operations) * `querysuggestions_total_search_requests`: sum of all [search requests](https://support.algolia.com/hc/en-us/articles/17245378392977-How-does-Algolia-count-records-and-operations) generated to build up query suggestions * `querysuggestions_total_acl_operations`: sum of all Query Suggestions [ACL operations](#acl-operations) metrics * `querysuggestions_total_indexing_operations`: sum of all Query Suggestions [indexing operations](#indexing-operations) metrics * `querysuggestions_total_records_operations`: sum of all Query Suggestions [record operations](#record-operations) metrics * `querysuggestions_total_synonym_operations`: sum of all Query Suggestions [synonym operations](#synonym-operations) metrics * `querysuggestions_total_rules_operations`: sum of all Query Suggestions [rule operations](#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](https://support.algolia.com/hc/en-us/articles/4406981934481) 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** * `search_operations`: all [Search operations](#search-operations) metrics in the same response * `acl_operations`: all [ACL operations](#acl-operations) metrics in the same response * `indexing_operations`: all [Indexing operations](#indexing-operations) metrics in the same response * `record_operations`: all [Record operations](#record-operations) metrics in the same response * `synonym_operations`: all [Synonym operations](#synonym-operations) metrics in the same response * `rule_operations`: all [Rule operations](#rule-operations) metrics in the same response **Example**: ```sh Command line icon=square-terminal theme={"system"} curl -X GET \ -H "X-Algolia-API-Key: $ALGOLIA_API_KEY" \ -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \ --compressed \ "https://usage.algolia.com/1/usage/records,max_qps,region_max_qps?startDate=$START_DATE&endDate=$END_DATE" ``` 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. ```jsonc JSON icon=braces theme={"system"} { "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 The lower bound timestamp (a string like "2006-01-02T00:00:00.000Z") of the time range to query. The upper bound timestamp (a string like "2006-01-02T23:23:59.999Z") of the time range to query. 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 name 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](#grouping). **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](#search-operations-2) metrics * `total_acl_operations`: sum of all [ACL operations](#acl-operations-2) metrics * `total_indexing_operations`: sum of all [Indexing operations](#indexing-operations-2) metrics * `total_records_operations`: sum of all [Record operations](#record-operations-2) metrics * `total_synonym_operations`: sum of all [Synonym operations](#synonym-operations-2) metrics * `total_rules_operations`: sum of all [Rule operations](#rule-operations-2) 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](/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/js). * `querysuggestions_total_search_operations`: sum of all [Search operations](#search-operations) * `querysuggestions_total_acl_operations`: sum of all [ACL operations](#acl-operations) metrics * `querysuggestions_total_indexing_operations`: sum of all [Indexing operations](#indexing-operations) metrics * `querysuggestions_total_records_operations`: sum of all [Record operations](#record-operations) metrics * `querysuggestions_total_synonym_operations`: sum of all [Synonym operations](#synonym-operations) metrics * `querysuggestions_total_rules_operations`: sum of all [Rule operations](#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** * `search_operations`: all [Search operations](#search-operations-2) metrics in the same response * `acl_operations`: all [ACL operations](#acl-operations-2) metrics in the same response * `indexing_operations`: all [Indexing operations](#indexing-operations-2) metrics in the same response * `record_operations`: all [Record operations](#record-operations-2) metrics in the same response * `synonym_operations`: all [Synonym operations](#synonym-operations-2) metrics in the same response * `rule_operations`: all [Rule operations](#rule-operations-2) metrics in the same response **Example**: ```sh Command line icon=square-terminal theme={"system"} curl -X GET \ -H "X-Algolia-API-Key: $ALGOLIA_API_KEY" \ -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \ --compressed \ "https://usage.algolia.com/1/usage/records,max_qps,region_max_qps/$INDEX_NAME?startDate=$START_DATE&endDate=$END_DATE" ``` 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. ```jsonc JSON icon=braces theme={"system"} { "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}}, // ... ] } ```