# Dividend Estimates

> Bavest's per-share dividend forecast.

`GET https://api.bavest.co/v2/dividends/estimates`

Group: Dividends. Route id: `v2_dividends_estimates`. Included in: Startup, Pro, Growth.

## Description

Bavest's per-share dividend forecast. Returns a per-share `amount` with
`lower` and `upper` bounds, one annual estimate per `date`, newest first.
Covers equities and ETFs. These are Bavest model forecasts, separate from
the analyst consensus under Estimates.

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

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

## Response

200 Successful response (`application/json`).

| Field | Type | Always present | Description |
|---|---|---|---|
| `data` | DividendEstimatesResponse | no | Bavest's own per-share dividend forecast, newest first. |
| `data.meta` | object | no |  |
| `data.meta.as_of` | string (date) | no | Newest estimate date in the set. Example: `2027-01-01`. |
| `data.meta.years` | integer | no | Number of fiscal years returned. Example: `3`. |
| `data.estimates` | array of DividendEstimate | no |  |
| `data.estimates[].date` | string (date) | no | Jan 1 of the fiscal year. Example: `2026-01-01`. |
| `data.estimates[].fiscal_year` | integer | no | Example: `2026`. |
| `data.estimates[].fiscal_year_end` | string (date) \| null | no | Example: `2026-12-31`. |
| `data.estimates[].expected_payment_year` | integer \| null | no | Example: `2027`. |
| `data.estimates[].amount` | number (double) | no | Dividend per share (point estimate, or the declared amount). Example: `3.49`. |
| `data.estimates[].lower` | number (double) | no | Lower bound (10th percentile). Example: `2.37`. |
| `data.estimates[].upper` | number (double) | no | Upper bound (90th percentile). Example: `5.24`. |
| `data.estimates[].basis` | string | no | declared once the fiscal year's payments are in the dividend calendar. One of `estimate`, `declared`. Example: `estimate`. |
| `data.estimates[].is_estimate` | boolean | no | false when basis is declared. Example: `true`. |
| `data.estimates[].source` | string | no | What carried the estimate. payout_policy: EPS consensus x the company's stated payout corridor. consensus_model: declared dividend grown on the EPS consensus. dividend_trend: no analyst coverage, the company's own dividend run-rate and trend. fmf: the FMF model. One of `payout_policy`, `consensus_model`, `dividend_trend`, `fmf`. Example: `consensus_model`. |
| `data.estimates[].payout_ratio` | number (double) \| null | no | Implied payout (amount / EPS consensus) where dividend and EPS share a currency. Example: `0.45`. |
| `data.estimates[].currency` | string \| null | no | Currency of the listing's dividend line (GBp for London lines). Example: `EUR`. |
| `data.estimates[].model` | object \| null | no | The FMF model estimate for the same year next to a consensus_model estimate. |
| `data.estimates[].model.amount` | number (double) | no |  |
| `data.estimates[].model.lower` | number (double) | no |  |
| `data.estimates[].model.upper` | number (double) | 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/dividends/estimates?symbol=AAPL' \
  -H "x-api-key: $BAVEST_API_KEY"
```

## Example response

```json
{
  "data": {
    "meta": {
      "as_of": "2028-01-01",
      "years": 3
    },
    "estimates": [
      {
        "date": "2028-01-01",
        "fiscal_year": 2028,
        "fiscal_year_end": "2028-09-27",
        "expected_payment_year": 2028,
        "amount": 1.1377,
        "lower": 0.9179,
        "upper": 1.659,
        "is_estimate": true,
        "basis": "estimate",
        "source": "consensus_model",
        "payout_ratio": 0.1064,
        "currency": "USD",
        "model": {
          "amount": 1.058,
          "lower": 1.038,
          "upper": 1.081
        }
      },
      {
        "date": "2027-01-01",
        "fiscal_year": 2027,
        "fiscal_year_end": "2027-09-27",
        "expected_payment_year": 2027,
        "amount": 1.08,
        "lower": 0.9785,
        "upper": 1.3983,
        "is_estimate": true,
        "basis": "estimate",
        "source": "consensus_model",
        "payout_ratio": 0.1125,
        "currency": "USD",
        "model": {
          "amount": 1.053,
          "lower": 1.039,
          "upper": 1.069
        }
      }
    ]
  },
  "meta": {
    "parameters": {
      "symbol": "AAPL"
    },
    "time": 2262
  }
}
```

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