# AI Estimates History

> Returns how an AI estimate for one metric evolved over time.

`GET https://api.bavest.co/v2/estimates/ai-estimates-history`

Group: Estimates. Route id: `v2_estimates_ai_estimates_history`. Included in: Startup, Pro, Growth.

## Description

Returns how an AI estimate for one metric evolved over time. Each
`prediction_date` snapshot is a revision. Revisions are attributed to
realized quarters, curated overrides, and the residual model re-estimate.

## Authentication

Send your API key in the `x-api-key` header on every request. No key yet? Sign up at https://dashboard.bavest.co/sign-up (free trial). The examples read the key from the `BAVEST_API_KEY` environment variable.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `symbol` | query | string | one of symbol, isin | Stock ticker symbol (e.g., `AAPL`, `MSFT`, `GOOGL`). Provide exactly one of symbol or isin. Example `AAPL`. |
| `isin` | query | string | one of symbol, isin | ISIN code (e.g., `US0378331005`). Provide exactly one of symbol or isin. Clear the symbol example before using an ISIN. |
| `metric` | query | string | yes | Single metric to trace, e.g. revenue, eps, ebitda. Example `revenue`. |
| `fiscal_year` | query | integer | no | Pin to one target fiscal year (target_date = Dec-31 of that year). Omit for all. Example when explicitly filtering: `2026`. |

Required: one of `symbol`, `isin`.

## Response

200 Successful response (`application/json`).

| Field | Type | Always present | Description |
|---|---|---|---|
| `data` | PredictionHistoryResponse | no | How a security's forecast for one metric evolved over time. |
| `data.metric` | string | no | Example: `revenue`. |
| `data.targets` | array of PredictionHistoryTarget | no |  |
| `data.targets[].target_date` | string (date) | no | Example: `2026-12-31`. |
| `data.targets[].fiscal_year` | integer | no | Calendar year of the target (January to December), for every company. Kept under this name for existing clients; read `calendar_year`. Example: `2026`. |
| `data.targets[].calendar_year` | integer | no | Calendar year of the target (January to December). Example: `2026`. |
| `data.targets[].realized` | boolean | no | Whether the calendar year has closed. Example: `false`. |
| `data.targets[].actual` | number (double) \| null | no | Realized actual once the year closes. |
| `data.targets[].current` | PredictionSnapshotDetail | no | A forecast snapshot with its nowcast decomposition. |
| `data.targets[].current.prediction_date` | string (date) | no | Example: `2026-08-01`. |
| `data.targets[].current.model_version` | string \| null | no | Example: `fmf-revenue-ensemble-v2`. |
| `data.targets[].current.point` | number (double) | no | Example: `105`. |
| `data.targets[].current.lower` | number (double) | no | Example: `95`. |
| `data.targets[].current.upper` | number (double) | no | Example: `115`. |
| `data.targets[].current.realized` | boolean \| null | no | Example: `false`. |
| `data.targets[].current.realized_sum` | number (double) \| null | no | Sum of realized (reported) quarters to date. Example: `45`. |
| `data.targets[].current.model_annual` | number (double) \| null | no | Model estimate of the full-year figure. Example: `100`. |
| `data.targets[].current.override_delta` | number (double) \| null | no | Net curated override applied. Example: `10`. |
| `data.targets[].current.overrides` | array of PredictionOverride \| null | no |  |
| `data.targets[].previous` | PredictionSnapshotDetail \| any \| null | no | Previous snapshot; null until at least one revision exists. |
| `data.targets[].previous.prediction_date` | string (date) | no | Example: `2026-08-01`. |
| `data.targets[].previous.model_version` | string \| null | no | Example: `fmf-revenue-ensemble-v2`. |
| `data.targets[].previous.point` | number (double) | no | Example: `105`. |
| `data.targets[].previous.lower` | number (double) | no | Example: `95`. |
| `data.targets[].previous.upper` | number (double) | no | Example: `115`. |
| `data.targets[].previous.realized` | boolean \| null | no | Example: `false`. |
| `data.targets[].previous.realized_sum` | number (double) \| null | no | Sum of realized (reported) quarters to date. Example: `45`. |
| `data.targets[].previous.model_annual` | number (double) \| null | no | Model estimate of the full-year figure. Example: `100`. |
| `data.targets[].previous.override_delta` | number (double) \| null | no | Net curated override applied. Example: `10`. |
| `data.targets[].previous.overrides` | array of PredictionOverride \| null | no |  |
| `data.targets[].revisions` | array of PredictionRevision | no |  |
| `data.targets[].revisions[].from_date` | string (date) | no | Example: `2026-05-01`. |
| `data.targets[].revisions[].to_date` | string (date) | no | Example: `2026-08-01`. |
| `data.targets[].revisions[].from_point` | number (double) | no | Example: `95`. |
| `data.targets[].revisions[].to_point` | number (double) | no | Example: `105`. |
| `data.targets[].revisions[].delta` | number (double) | no | Example: `10`. |
| `data.targets[].revisions[].drivers` | object | no | Attribution of the delta — realized quarters, curated overrides, and the residual model re-estimate (reconciles to delta). |
| `data.targets[].snapshots` | array of PredictionSnapshot | no | Full snapshot series, oldest first. |
| `data.targets[].snapshots[].prediction_date` | string (date) | no | Example: `2026-02-01`. |
| `data.targets[].snapshots[].model_version` | string \| null | no | Example: `fmf-revenue-ensemble-v2`. |
| `data.targets[].snapshots[].point` | number (double) | no | Example: `100`. |
| `data.targets[].snapshots[].lower` | number (double) \| null | no | Example: `90`. |
| `data.targets[].snapshots[].upper` | number (double) \| null | no | Example: `110`. |
| `data.targets[].snapshots[].realized` | boolean \| null | no | Example: `false`. |
| `data.targets[].snapshots[].realized_sum` | number (double) \| null | no | Sum of realized (reported) quarters to date. |
| `data.targets[].snapshots[].model_annual` | number (double) \| null | no | Model estimate of the full-year figure. |
| `data.targets[].snapshots[].override_delta` | number (double) \| null | no | Net curated override applied. |
| `data.targets[].snapshots[].overrides` | array of PredictionOverride \| null | no |  |
| `meta` | ResponseMeta | no | Response envelope metadata. Always present on a 200: `time` is set by `core/response.py` on every successful response. Errors carry the same block, built by the same code, so a client parses one meta shape whether the call succeeded or failed. |
| `meta.time` | integer | no | Server-side processing time in milliseconds. Example: `17`. |
| `meta.parameters` | object | no | Echo of the request parameters the endpoint resolved. |

## Example request

```bash
curl 'https://api.bavest.co/v2/estimates/ai-estimates-history?symbol=AAPL&metric=revenue' \
  -H "x-api-key: $BAVEST_API_KEY"
```

## Example response

```json
{
  "data": {
    "metric": "revenue",
    "targets": [
      {
        "target_date": "2026-12-31",
        "fiscal_year": 2026,
        "calendar_year": 2026,
        "realized": false,
        "current": {
          "prediction_date": "2026-10-02",
          "model_version": "revenue_lgb_purged_20261001",
          "point": 507772463812.5977,
          "lower": 466333211250.3338,
          "upper": 549211716374.8616,
          "realized": false,
          "realized_sum": 220601000000,
          "model_annual": 520839081098.4933,
          "override_delta": 0,
          "overrides": []
        },
        "previous": {
          "prediction_date": "2026-10-01",
          "model_version": "revenue_lgb_purged_20261001",
          "point": 507772463812.5977,
          "lower": 466333211250.3338,
          "upper": 549211716374.8616,
          "realized": false,
          "realized_sum": 220601000000,
          "model_annual": 520839081098.4933,
          "override_delta": 0,
          "overrides": []
        },
        "actual": null,
        "revisions": [
          {
            "from_date": "2026-05-22",
            "to_date": "2026-09-29",
            "from_point": 273563944311.7156,
            "to_point": 474072675596.5948,
            "delta": 200508731284.8792,
            "drivers": {
              "model": 200508731284.8792
            }
          },
          {
            "from_date": "2026-09-29",
            "to_date": "2026-09-30",
            "from_point": 474072675596.5948,
            "to_point": 499387888309.2173,
            "delta": 25315212712.6225,
            "drivers": {
              "realized": 220601000000,
              "override": 0,
              "model": -195285787287.3775
            }
          }
        ],
        "snapshots": [
          {
            "prediction_date": "2026-05-22",
            "model_version": "fmf-revenue-ensemble-v2",
            "point": 273563944311.7156,
            "lower": 173461359907.0481,
            "upper": 373666528716.3831,
            "realized": null,
            "realized_sum": null,
            "model_annual": null,
            "override_delta": null,
            "overrides": null
          },
          {
            "prediction_date": "2026-09-29",
            "model_version": "revenue_lgb_auto_20260526",
            "point": 474072675596.5948,
            "lower": 405663311114.142,
            "upper": 542482040079.0475,
            "realized": false,
            "realized_sum": 0,
            "model_annual": 474072675596.5948,
            "override_delta": 0,
            "overrides": []
          }
        ]
      },
      {
        "target_date": "2025-12-31",
        "fiscal_year": 2025,
        "calendar_year": 2025,
        "realized": false,
        "current": {
          "prediction_date": "2026-06-10",
          "model_version": "revenue_lgb_auto_20260526",
          "point": 438596944379.3873,
          "lower": 417422737937.1071,
          "upper": 459771150821.6675,
          "realized": false,
          "realized_sum": 291861000000,
          "model_annual": 466321780248.617,
          "override_delta": 0,
          "overrides": []
        },
        "previous": {
          "prediction_date": "2026-06-09",
          "model_version": "revenue_lgb_growth_20260527",
          "point": 407304071346.03,
          "lower": 390645471196.2831,
          "upper": 423962671495.777,
          "realized": false,
          "realized_sum": 291861000000,
          "model_annual": 366874106921.3515,
          "override_delta": 0,
          "overrides": []
        },
        "actual": null,
        "revisions": [
          {
            "from_date": "2026-06-04",
            "to_date": "2026-06-05",
            "from_point": 407270732407.1996,
            "to_point": 407270732407.1996,
            "delta": 0,
            "drivers": {
              "realized": 0,
              "override": 0,
              "model": 0
            }
          },
          {
            "from_date": "2026-06-05",
            "to_date": "2026-06-06",
            "from_point": 407270732407.1996,
            "to_point": 407270732407.1996,
            "delta": 0,
            "drivers": {
              "realized": 0,
              "override": 0,
              "model": 0
            }
          }
        ],
        "snapshots": [
          {
            "prediction_date": "2026-06-04",
            "model_version": "revenue_lgb_growth_20260527",
            "point": 407270732407.1996,
            "lower": 390616943113.9633,
            "upper": 423924521700.436,
            "realized": false,
            "realized_sum": 291861000000,
            "model_annual": 366768156921.3515,
            "override_delta": 0,
            "overrides": []
          },
          {
            "prediction_date": "2026-06-05",
            "model_version": "revenue_lgb_growth_20260527",
            "point": 407270732407.1996,
            "lower": 390616943113.9633,
            "upper": 423924521700.436,
            "realized": false,
            "realized_sum": 291861000000,
            "model_annual": 366768156921.3515,
            "override_delta": 0,
            "overrides": []
          }
        ]
      }
    ]
  },
  "meta": {
    "parameters": {
      "metric": "revenue",
      "symbol": "AAPL"
    },
    "time": 2524
  }
}
```

## Errors

| Status | Meaning |
|---|---|
| 400 | Invalid request parameters. Returned when required query parameters are missing, have invalid types, or violate constraints (e.g., providing both symbol and isin when they are mutually exclusive). |
| 401 | Missing or invalid API key. |
| 404 | Resource not found. |
| 429 | Rate limit exceeded. Retry after the `Retry-After` header interval. |
| 500 | An unexpected error occurred on the server. If the issue persists, contact support with the X-Request-Id header value. |
| 502 | Upstream data provider returned an error or is temporarily unavailable. Retry after a short delay. |
| 504 | The request timed out waiting for a response from the upstream data provider. This may occur for complex queries or during peak load. |
| default | An unexpected error occurred on the server. If the issue persists, contact support with the X-Request-Id header value. |

- `403` from the gateway: the API key is invalid or switched off.
- `429` with message `Limit Exceeded`: the monthly quota of the key is used up. With `Too Many Requests`: the key is throttled, or this route is not in the key's plan. Wait for `Retry-After` when it is sent.

## Links

- HTML page: https://dashboard.bavest.co/docs/v2_estimates_ai_estimates_history
- OpenAPI: https://dashboard.bavest.co/openapi.json (YAML: https://dashboard.bavest.co/openapi.yaml)
- Authentication: https://dashboard.bavest.co/docs/authentication.md
- MCP server for AI agents: https://dashboard.bavest.co/docs/mcp.md
- All routes: https://dashboard.bavest.co/llms.txt