For AI agents: complete Markdown index · compact index. Follow the explicit .md links for the Markdown version of each page.

Estimates

AI Estimates

POST/v2/estimates/ai-estimates

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.

Included in: Startup, Pro, Growth.

Authentication

Send your API key in the x-api-key header on every request to https://api.bavest.co. The samples read it from the BAVEST_API_KEY environment variable. Get an API key (free trial) · Authentication guide.

Parameters

This route takes no path or query parameters.

Request body

JSON, required.

Draft from the schema. Review and fill in required fields before sending.

  • symbol
    string
    required

    Ticker symbol, ISIN, or CUSIP. Resolved server-side.

    Example: AAPL

  • metrics
    array of string

    Restrict to these metrics. Omit for all. Also accepts a comma-separated string.

  • task_types
    array of string

    Restrict to these task types. Omit for all.

    Each item is one of regression, classification, sequence, hazard.

Response 200

Successful response · application/json

  • data
    PredictionsResponse

    Model predictions for a security.

    2 fields in data
    • meta
      ForecastMeta

      Freshness summary for the returned forecast set.

      2 fields in meta
      • as_of
        string (date)

        Most recent prediction_date across the returned rows.

        Example: 2026-05-20

      • model_version
        string

        Model version of the newest returned row.

        Example: fmf-eps-v1.4

    • predictions
      array of PredictionRecord
      9 fields in predictions
      • symbol
        string

        Ticker symbol (rows are self-describing).

        Example: AAPL

      • metric
        string

        Forecast metric, e.g. eps, revenue, ebitda, dividend.

        Example: eps

      • task_type
        string

        Prediction task type.

        One of regression, classification, sequence, hazard.

        Example: regression

      • target_date
        string (date)

        Period the forecast is for.

        Example: 2026-09-30

      • prediction_date
        string (date)

        Point-in-time the forecast was generated.

        Example: 2026-05-20

      • model_version
        string

        Example: fmf-eps-v1.4

      • frequency
        string

        Reporting frequency of the target.

        Example: quarterly

      • prediction
        RegressionPrediction | ClassificationPrediction | HazardPrediction

        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.

        7 fields in prediction
        • point
          number (double)

          Example: 2.41

        • lower
          number (double)

          Example: 2.18

        • upper
          number (double)

          Example: 2.65

        • components
          object

          Forecast decomposition (e.g. trend/seasonal).

        • direction
          string | null

          Direction of the forecast against the trailing value. Null without a trailing value.

          One of up, down.

          Example: up

        • direction_score
          number (double) | null

          Forecast minus trailing value, in the metric's own unit (not normalized).

          Example: 0.12

        • nowcast
          object | null

          Intra-year breakdown for annual targets once quarters of the year are reported. Null otherwise.

          15 fields in nowcast
          • method
            string

            Example: nowcast

          • fiscal_year
            integer

            Calendar year of the target (January to December), for every company. Kept under this name for existing clients; read calendar_year.

            Example: 2026

          • calendar_year
            integer

            Calendar year of the target (January to December). MSFT 2026 is January to December 2026, not its fiscal year ending June 2026.

            Example: 2026

          • realized
            boolean

            Whether the calendar year has closed.

          • realized_sum
            number (double)

            Sum of the reported quarters so far.

          • realized_quarters
            array of string (date)
          • remaining_quarters
            array of string (date)
          • w_realized
            number (double)

            Weight of the reported part of the year.

          • seasonality_source
            string
          • model_annual
            number (double) | null

            Model estimate of the full-year figure.

          • remaining_estimate
            number (double) | null
          • override_delta
            number (double)

            Net curated override applied.

          • overrides
            array of PredictionOverride
            2 fields in overrides
            • reason
              string

              Example: signed supply deal

            • value
              number (double)

              Example: 10

          • annual_actual
            number (double) | null
          • notes
            array of string
      • explainability
        ForecastExplainability | null

        Top contributing features for the prediction (SHAP), when available.

        1 field in explainability
        • top_features
          array of object
          2 fields in top_features
          • name
            string

            Feature name.

            Example: revenue_ttm

          • shap
            number (double)

            SHAP contribution.

            Example: 0.42

  • meta
    ResponseMeta

    Response metadata, including server-side processing time and resolved request parameters. Successful and error responses use the same metadata shape.

    2 fields in meta
    • time
      integer

      Server-side processing time in milliseconds

      Example: 17

    • parameters
      object

      Echo of the request parameters the endpoint resolved

Errors

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

For AI agents: this page as Markdown at /docs/v2_estimates_ai_estimates.md, every route in /llms.txt, the OpenAPI spec at /openapi.json.