# $percentiles

`$percentiles` returns percentile cut points for a field.

A percentile tells you the value below which a percentage of observations fall.

- `50`th percentile: median-like center point
- `95`th percentile: tail latency/price threshold
- `99`th percentile: extreme tail threshold

### Compatibility

| Field Type | Supported |
|------------|-----------|
| TEXT | No |
| U64/I64/F64 | Yes |
| DATE | Yes |
| BOOL | No |
| KEYWORD | No |
| FACET | No |

Field must be `FAST`.

### Arguments

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `field` | `string` | Yes | Field to aggregate. |
| `percents` | `number[]` | No | Percent points to calculate (for example `[50, 95, 99]`). |
| `keyed` | `boolean` | No | If `true` (default), returns a map. If `false`, returns an array of `{ key, value }`. |
| `missing` | `number` | No | Fallback value for missing fields. |

If `percents` is omitted, defaults to `[1.0, 5.0, 25.0, 50.0, 75.0, 95.0, 99.0]`.

<Tabs>

<Tab title="TypeScript">
```ts
await index.aggregate({
  aggregations: {
    latency_pct: {
      $percentiles: { field: "latencyMs", percents: [50, 95, 99], keyed: true },
    },
  },
});
```
</Tab>

<Tab title="Python">
```python
index.aggregate(
    aggregations={
        "latency_pct": {
            "$percentiles": {
                "field": "latencyMs",
                "percents": [50, 95, 99],
                "keyed": True,
            }
        }
    }
)
```
</Tab>

<Tab title="Redis CLI">
```bash
SEARCH.AGGREGATE logs '{}' '{"latency_pct": {"$percentiles": {"field": "latencyMs", "percents": [50, 95, 99], "keyed": true}}}'
```
</Tab>

</Tabs>

### Output

`keyed: true` (default):

```json
{
  "values": {
    "50.0": 40,
    "95.0": 76,
    "99.0": 79.2
  }
}
```

`keyed: false`:

```json
{
  "values": [
    { "key": 50, "value": 40 },
    { "key": 95, "value": 76 },
    { "key": 99, "value": 79.2 }
  ]
}
```