# Mindshare forecast

- Method: `GET`
- Path: `/forecasts/mindshare`
- Credits: 5 (10 with refresh=true; free if not_forecastable, 30 an hour)
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-forecasts-mindshare/
- Interactive docs: https://docs.hiddensystems.ai/nebula/api/#endpoint=get-forecasts-mindshare

## Description

Where an asset's mindshare is likely to be over the next 72 hours, as a range of outcomes with their chances. `series` gives the distribution every 4 hours; `chance_higher_72h` and `likely_low_share` to `likely_high_share` summarise where it lands; `takeoff_chance_72h` is the chance of a sudden surge in attention.

Forecasts update within a minute of new posts about the asset, and at least every 15 minutes. `refresh=true` recomputes on the latest data in about 5 seconds; if that takes over 20, you get the latest forecast with `refreshed: false`, charged at 5. Assets without a forecast return `status: not_forecastable` with a `reason`; /forecasts/assets lists the assets that have one.

Costs 5 credits, or 10 with `refresh=true`. `not_forecastable` answers are free, up to 30 an hour per account; past that this endpoint returns 429 until the hour clears.

## cURL Example

```bash
curl --get \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/forecasts/mindshare' \
  --data-urlencode 'asset_id=NVDA' \
  --data-urlencode 'asset_class=equity' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

No path parameters for this endpoint.

## Query Parameters

- `asset_id` (string, required): Asset ID from /assets or /search, such as NVDA, GLD, SPX, or bitcoin. Send it with the asset_class returned alongside it.
- `asset_class` (string, required, allowed: equity, commodity, index, crypto): Class of the asset named by asset_id: equity (stocks and ETFs), commodity, index, or crypto. Send the asset_class that /assets or /search returned alongside the asset_id.
- `refresh` (boolean, optional): true recomputes the forecast on the latest data: 10 credits, about 5 seconds. Defaults to false.

## Response

OK

- `as_of` (string (date-time), required): UTC start of the forecast: the end of the last complete 15 minutes it was computed from. Null when the asset has never been scored.
- `chance_higher_72h` (number (double), required): The chance the share is higher than current_share in 72 hours, from 0 to 1.
- `current_share` (number (double), required): The asset's share at as_of, from 0 to 1: where every path starts, and the value the chances are measured against.
- `horizon_hours` (integer, required): How far ahead the forecast runs, in hours: always 72.
- `likely_high_share` (number (double), required): The 90th percentile of the share in 72 hours: a 90% chance of ending below it.
- `likely_low_share` (number (double), required): The 10th percentile of the share in 72 hours: a 90% chance of ending above it.
- `reason` (string, required, enum: too_little_history, stale_data, missing_price, ): Why the asset cannot be forecast: too_little_history, stale_data, or missing_price. Null when status is ok.
- `refreshed` (boolean, required): True when this request re-ran the forecast (refresh=true and the re-run finished in time); false when it is the latest scheduled five-minute forecast.
- `sample_paths` (array<array<number (double)>>, required): 24 possible paths for the share, each aligned with series. Draw them to show the spread of outcomes.
- `series` (array<object>, required): The forecast distribution every 4 hours from as_of: 18 steps, oldest first.
- `series[].mean_share` (number (double), required): The expected share at this step.
- `series[].p10_share` (number (double), required): The 10th percentile of the share at this step, from 0 to 1.
- `series[].p25_share` (number (double), required): The 25th percentile of the share at this step, from 0 to 1.
- `series[].p50_share` (number (double), required): The 50th percentile of the share at this step, from 0 to 1.
- `series[].p75_share` (number (double), required): The 75th percentile of the share at this step, from 0 to 1.
- `series[].p90_share` (number (double), required): The 90th percentile of the share at this step, from 0 to 1.
- `series[].quantile_shares` (array<number (double)>, required): 21 quantiles of the share at this step: the 0th, 5th, 10th, ... 100th percentiles, lowest first. Interpolate between them for the chance of landing in any range.
- `series[].timestamp` (string (date-time), required): UTC time the step forecasts: as_of plus 4, 8, ... 72 hours.
- `status` (string, required, enum: ok, not_forecastable): ok, or not_forecastable when the asset cannot be forecast (the summary fields are then null and the series empty; reason says why).
- `takeoff_chance_72h` (number (double), required): The chance of a sudden surge in attention on the asset within 72 hours, from 0 to 1. Null when there is no estimate.

Media type: `application/json`

## JSON Response

```json
{
  "as_of": "2026-09-14T09:15:00Z",
  "chance_higher_72h": 0.63,
  "current_share": 0.0498,
  "horizon_hours": 72,
  "likely_high_share": 0.1022,
  "likely_low_share": 0.0331,
  "reason": null,
  "refreshed": false,
  "sample_paths": [
    [
      0.0502,
      0.0515,
      0.0531
    ],
    [
      0.0494,
      0.0488,
      0.0479
    ]
  ],
  "series": [
    {
      "mean_share": 0.0512,
      "p10_share": 0.039936000000000006,
      "p25_share": 0.045568000000000004,
      "p50_share": 0.050176,
      "p75_share": 0.055296000000000005,
      "p90_share": 0.063488,
      "quantile_shares": [
        0.0301,
        0.0352,
        0.0391,
        0.0418,
        0.0437,
        0.0451,
        0.0463,
        0.0474,
        0.0484,
        0.0493,
        0.0502,
        0.0511,
        0.0521,
        0.0532,
        0.0544,
        0.0557,
        0.0573,
        0.0594,
        0.0623,
        0.0671,
        0.0889
      ],
      "timestamp": "2026-09-14T13:15:00Z"
    },
    {
      "mean_share": 0.0523,
      "p10_share": 0.040794000000000004,
      "p25_share": 0.046547,
      "p50_share": 0.051254,
      "p75_share": 0.056484,
      "p90_share": 0.06485199999999999,
      "quantile_shares": [
        0.0301,
        0.0352,
        0.0391,
        0.0418,
        0.0437,
        0.0451,
        0.0463,
        0.0474,
        0.0484,
        0.0493,
        0.0502,
        0.0511,
        0.0521,
        0.0532,
        0.0544,
        0.0557,
        0.0573,
        0.0594,
        0.0623,
        0.0671,
        0.0889
      ],
      "timestamp": "2026-09-14T17:15:00Z"
    },
    {
      "mean_share": 0.0534,
      "p10_share": 0.041652,
      "p25_share": 0.047526000000000006,
      "p50_share": 0.052332000000000004,
      "p75_share": 0.05767200000000001,
      "p90_share": 0.066216,
      "quantile_shares": [
        0.0301,
        0.0352,
        0.0391,
        0.0418,
        0.0437,
        0.0451,
        0.0463,
        0.0474,
        0.0484,
        0.0493,
        0.0502,
        0.0511,
        0.0521,
        0.0532,
        0.0544,
        0.0557,
        0.0573,
        0.0594,
        0.0623,
        0.0671,
        0.0889
      ],
      "timestamp": "2026-09-14T21:15:00Z"
    }
  ],
  "status": "ok",
  "takeoff_chance_72h": 0.21
}
```