--- type: api title: Get field usage stats description: Get field usage information for each shard and field of an index. url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/operation/operation-indices-field-usage-stats resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/operation/operation-indices-field-usage-stats products: - Elasticsearch --- # Get field usage stats Availability: 7.15+ ## Paths - `GET` `/{index}/_field_usage_stats` - [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#apikeyauth) - [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#basicauth) - [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#bearerauth) #### Path Parameters - `index` (union IndexName | [] IndexName) Comma-separated list or wildcard expression of index names used to limit the request. ## Description Get field usage information for each shard and field of an index. Field usage statistics are automatically captured when queries are running on a cluster. A shard-level search request that accesses a given field, even if multiple times during that request, is counted as a single use. The response body reports the per-shard usage count of the data structures that back the fields in the index. A given request will increment each count by a maximum value of 1, even if the request accesses the same field multiple times. ## Required authorization * Index privileges: `manage` ## Query String Parameters - `allow_no_indices` (boolean) If `false`, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. - `expand_wildcards` (string ExpandWildcards · default: open) Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as `open,hidden`. Supported values include: - `all`: Match any data stream or index, including hidden ones. - `open`: Match open, non-hidden indices. Also matches any non-hidden data stream. - `closed`: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed. - `hidden`: Match hidden data streams and hidden indices. Must be combined with `open`, `closed`, or `both`. - `none`: Wildcard expressions are not accepted. Values: `all`, `open`, `closed`, `hidden`, `none` - `ignore_unavailable` (boolean · default: false) If `true`, missing or closed indices are not included in the response. - `fields` (union Fields) Comma-separated list or wildcard expressions of fields to include in the statistics. One of: `Field` or `Field[]` ## Response `application/json` - `_shards` ({} ShardStatistics) - `failed` (number uint) The number of shards the operation or search attempted to run on but failed. - `successful` (number uint) The number of shards the operation or search succeeded on. - `total` (number uint) The number of shards the operation or search will run on overall. - `failures` ([] ShardFailure) - `index` (string IndexName) - `node` (string) - `reason` ({} ErrorCause) - `type` (string) The type of error - `reason` (union string) — nullable A human-readable explanation of the error, in English. One of: `string` - `stack_trace` (string) The server stack trace. Present only if the `error_trace=true` parameter was sent with the request. - `caused_by` ({} ErrorCause) — recursive Same fields as `reason` in `failures` - `root_cause` ([] ErrorCause) — recursive Same fields as `reason` in `failures` - `suppressed` ([] ErrorCause) — recursive Same fields as `reason` in `failures` - `shard` (number) - `status` (string) - `primary` (boolean) - `skipped` (number uint) ## Code Examples #### Console ```console GET /my-index-000001/_field_usage_stats ``` #### JavaScript ```javascript const response = await client.indices.fieldUsageStats({ index: "my-index-000001", }); ``` #### Python ```python resp = client.indices.field_usage_stats( index="my-index-000001", ) ``` #### curl ```curl curl -X GET "$ELASTICSEARCH_URL/my-index-000001/_field_usage_stats" \ -H "Authorization: ApiKey $ELASTIC_API_KEY" ``` #### Java ```java client.indices().fieldUsageStats(f -> f .index("my-index-000001") ); ``` #### C# ```c# var response = await client.Indices.FieldUsageStatsAsync(indices: new[] { "my-index-000001" }); ``` #### PHP ```php $resp = $client->indices()->fieldUsageStats([ "index" => "my-index-000001", ]); ``` #### Ruby ```ruby response = client.indices.field_usage_stats( index: "my-index-000001" ) ``` ## Response Examples #### Indices field usage stats response example1 An abbreviated response from `GET /my-index-000001/_field_usage_stats`. The `all_fields` object reports the sums of the usage counts for all fields in the index (on the listed shard). ```json { "_shards": { "total": 1, "successful": 1, "failed": 0 }, "my-index-000001": { "shards": [ { "tracking_id": "MpOl0QlTQ4SYYhEe6KgJoQ", "tracking_started_at_millis": 1625558985010, "routing": { "state": "STARTED", "primary": true, "node": "gA6KeeVzQkGURFCUyV-e8Q", "relocating_node": null }, "stats": { "all_fields": { "any": "6", "inverted_index": { "terms": 1, "postings": 1, "proximity": 1, "positions": 0, "term_frequencies": 1, "offsets": 0, "payloads": 0 }, "stored_fields": 2, "doc_values": 1, "points": 0, "norms": 1, "term_vectors": 0, "knn_vectors": 0 }, "fields": { "_id": { "any": 1, "inverted_index": { "terms": 1, "postings": 1, "proximity": 1, "positions": 0, "term_frequencies": 1, "offsets": 0, "payloads": 0 }, "stored_fields": 1, "doc_values": 0, "points": 0, "norms": 0, "term_vectors": 0, "knn_vectors": 0 }, "_source": {}, "context": {}, "message.keyword": {} } } } ] } } ```