> For the complete documentation index, see [llms.txt](https://docs.synthdata.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.synthdata.co/prediction-percentiles.md).

# Prediction Percentiles

```
GET /insights/prediction-percentiles
```

## Parameters

| Parameter | Type    | Required | Default | Description                                                                                              |
| --------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------------- |
| asset     | string  | Yes      | —       | Asset symbol: `BTC`, `ETH`, `SOL`, `HYPE`, `XRP`,`XAU`, `WTIOIL`, `SPY`, `NVDA`, `TSLA`, `AAPL`, `GOOGL` |
| horizon   | string  | no       | low     | Forecast horizon: `1h` for 1-hour, `24h` for 24-hour.                                                    |
| days      | integer | No       | 14      | Number of days to aggregate for the meta-leaderboard ranking                                             |
| limit     | integer | No       | 10      | Number of top miners from the meta-leaderboard to use for analysis                                       |

## Headers

| Header        | Required | Description                              |
| ------------- | -------- | ---------------------------------------- |
| Authorization | Yes      | API key in format: `Apikey YOUR_API_KEY` |

{% hint style="info" %}
Include your API key in the Authorization header exactly as shown: `Apikey YOUR_API_KEY`.
{% endhint %}

## Example Requests

{% code title="curl" %}

```bash
curl "https://api.synthdata.co/insights/prediction-percentiles?asset=BTC" \
  -H "Authorization: Apikey YOUR_API_KEY"
```

{% endcode %}

**Example Request (1-Hour Horizon)**

```bash
curl "https://api.synthdata.co/insights/prediction-percentiles?asset=BTC&horizon=1h" \
  -H "Authorization: Apikey YOUR_API_KEY"
```

## Response

{% code title="response.json" %}

```json
{
  "current_price": 88996.66,
  "forecast_future": {
    "percentiles": [
      {
        "0.005": 88996.66,
        "0.05": 88996.66,
        "0.2": 88996.66,
        "0.35": 88996.66,
        "0.5": 88996.66,
        "0.65": 88996.66,
        "0.8": 88996.66,
        "0.95": 88996.66,
        "0.995": 88996.66
      },
      {
        "0.005": 88631.35,
        "0.05": 88765.15,
        "0.2": 88879.70,
        "0.35": 88943.39,
        "0.5": 88998.23,
        "0.65": 89055.24,
        "0.8": 89122.30,
        "0.95": 89236.58,
        "0.995": 89359.79
      }
    ]
  },
  "forecast_past": {
    "percentiles": [...]
  },
  "realized": {
    "prices": [...],
    "percentiles": [...]
  }
}
```

{% endcode %}

## Field Descriptions

| Field                        | Description                                                                            |
| ---------------------------- | -------------------------------------------------------------------------------------- |
| current\_price               | Current asset price                                                                    |
| forecast\_future.percentiles | Array of percentile objects, one per 5-minute time step (289 total for 24h, 61 for 1h) |
| 0.005, 0.05, etc.            | Price at that percentile (0.5 = median, 0.95 = 95th percentile)                        |
| forecast\_past.percentiles   | Historical percentile predictions                                                      |
| realized.prices              | Actual historical prices with returns                                                  |
| realized.percentiles         | Realized price percentiles                                                             |

## Response Codes

| Code | Description                               |
| ---- | ----------------------------------------- |
| 200  | Success - returns percentile data         |
| 400  | Bad Request - invalid parameters          |
| 401  | Unauthorized - invalid or missing API key |
| 500  | Internal Server Error                     |