# AI Estimates

> Bavest's own AI estimates for a security across task types (regression, classification, sequence, hazard).

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

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

## Description

Bavest's own AI estimates for a security across task types (regression,
classification, sequence, hazard). Filter with `metrics` and `task_types`.
Omit both to return everything.

One prediction per metric, task type, target and frequency: the newest.
A target whose period ended more than 120 days ago without an actual is
left out, its figure is reported by then; earlier forecasts are on
`/v2/estimates/ai-estimates-history`. Annual targets are calendar years
(January to December) for every company, also where the fiscal year ends
in another month: MSFT 2026 covers January to December 2026, not the
fiscal year ending June 2026.

## 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

None.

## Request body

JSON, required.

| Field | Type | Always present | Description |
|---|---|---|---|
| `symbol` | string | yes | Ticker symbol, ISIN, or CUSIP. Resolved server-side. Example: `AAPL`. |
| `metrics` | array of string | no | Restrict to these metrics. Omit for all. Also accepts a comma-separated string. |
| `task_types` | array of string | no | Restrict to these task types. Omit for all. |

## Response

200 Successful response (`application/json`).

| Field | Type | Always present | Description |
|---|---|---|---|
| `data` | PredictionsResponse | no | Model predictions for a security. |
| `data.meta` | ForecastMeta | no | Freshness summary for the returned forecast set. |
| `data.meta.as_of` | string (date) | no | Most recent prediction_date across the returned rows. Example: `2026-05-20`. |
| `data.meta.model_version` | string | no | Model version of the newest returned row. Example: `fmf-eps-v1.4`. |
| `data.predictions` | array of PredictionRecord | no |  |
| `data.predictions[].symbol` | string | no | Ticker symbol (rows are self-describing). Example: `AAPL`. |
| `data.predictions[].metric` | string | no | Forecast metric, e.g. eps, revenue, ebitda, dividend. Example: `eps`. |
| `data.predictions[].task_type` | string | no | Prediction task type. One of `regression`, `classification`, `sequence`, `hazard`. Example: `regression`. |
| `data.predictions[].target_date` | string (date) | no | Period the forecast is for. Example: `2026-09-30`. |
| `data.predictions[].prediction_date` | string (date) | no | Point-in-time the forecast was generated. Example: `2026-05-20`. |
| `data.predictions[].model_version` | string | no | Example: `fmf-eps-v1.4`. |
| `data.predictions[].frequency` | string | no | Reporting frequency of the target. Example: `quarterly`. |
| `data.predictions[].prediction` | RegressionPrediction \| ClassificationPrediction \| HazardPrediction | no | Payload shape varies by task_type. Uses anyOf, not oneOf: the three variants overlap (all carry point/lower/upper) and nothing in the payload discriminates them, so oneOf rejected every real response. |
| `data.predictions[].prediction.point` | number (double) | no | Example: `2.41`. |
| `data.predictions[].prediction.lower` | number (double) | no | Example: `2.18`. |
| `data.predictions[].prediction.upper` | number (double) | no | Example: `2.65`. |
| `data.predictions[].prediction.components` | object | no | Forecast decomposition (e.g. trend/seasonal). |
| `data.predictions[].prediction.direction` | string \| null | no | Direction of the forecast against the trailing value. Null without a trailing value. One of `up`, `down`. Example: `up`. |
| `data.predictions[].prediction.direction_score` | number (double) \| null | no | Forecast minus trailing value, in the metric's own unit (not normalized). Example: `0.12`. |
| `data.predictions[].prediction.nowcast` | object \| null | no | Intra-year breakdown for annual targets once quarters of the year are reported. Null otherwise. |
| `data.predictions[].explainability` | ForecastExplainability \| null | no | Top contributing features for the prediction (SHAP), when available. |
| `data.predictions[].explainability.top_features` | array of object | 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 -X POST 'https://api.bavest.co/v2/estimates/ai-estimates' \
  -H "x-api-key: $BAVEST_API_KEY" \
  -H 'content-type: application/json' \
  --data '{"symbol":"AAPL","metrics":["eps","revenue"],"task_types":["regression"]}'
```

## Example response

```json
{
  "data": {
    "meta": {
      "as_of": "2026-05-20",
      "model_version": "ai-eps-v1.4"
    },
    "predictions": [
      {
        "symbol": "AAPL",
        "metric": "eps",
        "task_type": "regression",
        "target_date": "2026-09-30",
        "prediction_date": "2026-05-20",
        "model_version": "ai-eps-v1.4",
        "frequency": "quarterly",
        "prediction": {
          "point": 2.41,
          "lower": 2.18,
          "upper": 2.65,
          "components": {
            "trend": 2.3,
            "seasonal": 0.11
          }
        },
        "explainability": {
          "top_features": [
            {
              "name": "revenue_ttm",
              "shap": 0.42
            },
            {
              "name": "gross_margin",
              "shap": 0.19
            }
          ]
        }
      }
    ]
  },
  "meta": {
    "parameters": {
      "symbol": "AAPL",
      "metrics": [
        "eps"
      ],
      "task_types": [
        "regression"
      ]
    },
    "time": 12
  }
}
```

## 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
- 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