canonical: https://jentic.com/apis/amazonaws.com/amazon-forecast-query-service

# AWS Amazon Forecast Query Service

Jentic publishes the only available OpenAPI specification for Amazon Forecast Query Service, keeping it validated and agent-ready. The Forecast Query Service is the runtime side of Amazon Forecast and exposes only the operations needed to query trained predictors. The API returns point and quantile forecasts for a specific item, and serves what-if forecasts that compare baseline predictions against scenario adjustments. It is built for application teams that want to embed pre-computed Forecast predictions into customer-facing demand, capacity, or pricing flows.

## For AI agents

Query Amazon Forecast predictors for point and quantile forecasts, including baseline and what-if scenarios for a specific item.

## Scope

Does not train predictors, manage datasets, or evaluate models - use for runtime queries against Amazon Forecast outputs only.

## Capabilities

- Query a deployed Forecast predictor for a single item across the prediction horizon
- Retrieve quantile values such as p10, p50, and p90 alongside point forecasts
- Filter forecasts by item identifier and additional dataset dimensions
- Query what-if forecasts that compare a baseline against scenario adjustments
- Receive forecasts as time-stamped data points ready for charting or downstream logic

## Use cases

### Demand Forecast Retrieval

E-commerce and retail teams use the Forecast Query Service to retrieve item-level demand forecasts produced by Amazon Forecast and surface them inside fulfilment, replenishment, and pricing applications. The API returns point forecasts and configurable quantiles for a single item per call, so downstream systems can read confidence bands and not just a midpoint estimate. Forecast values arrive as date-keyed series ready to be plotted or fed into stock decisions.

Example prompt: Query forecast arn:aws:forecast:...:forecast/demand-prod with filter item_id=SKU-12345 and return p10, p50, and p90 values.

### What-If Scenario Comparison

Planning teams use the QueryWhatIfForecast operation to compare baseline forecasts against scenarios that alter price, promotion, or holiday inputs. The API returns both baseline and scenario series for a single item, so analysts can view the lift or drag attributable to each scenario without computing the difference manually. This shortens scenario analysis for category managers and supply planners.

Example prompt: Call QueryWhatIfForecast for what-if forecast id wif-xyz with filter item_id=SKU-12345 and return baseline plus scenario series.

### Operational Embedding in Customer-Facing Apps

Product and operations teams embed Forecast predictions into staffing, capacity, and pricing surfaces by calling QueryForecast at runtime. Because the API exposes only two operations, integration is small and stable, and the rest of the Forecast lifecycle (training, evaluation) stays inside the separate Forecast control plane. This separation keeps customer-facing services lightweight.

Example prompt: Call QueryForecast for forecast staffing-monthly with filter location_id=eu-west-store-42 and return the next 14 daily values.

### Agent-Driven Forecast Lookup via Jentic

AI agents use the Forecast Query Service through Jentic to fetch demand or capacity predictions in response to user questions and workflow events. Jentic exposes the QueryForecast and QueryWhatIfForecast operations as discoverable tools so an agent can search by intent and return forecast values to a chat interface or downstream automation in seconds.

Example prompt: Search Jentic for query forecast, load the QueryForecast schema, and execute it with forecast ARN demand-q3 and filter item_id=SKU-9001.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /#X-Amz-Target=AmazonForecastRuntime.QueryForecast | Query a deployed forecast for a single item |
| POST | /#X-Amz-Target=AmazonForecastRuntime.QueryWhatIfForecast | Query a what-if forecast for baseline and scenario series |

## Key resources

- **Forecasts** — Trained predictor outputs queried by item and date filters
- **What-If Forecasts** — Scenario forecast outputs queried with baseline and scenario series

## Why Jentic

- **Setup:** Wiring the Amazon Forecast Query Service by hand means building SigV4 request signing, resolving the regional forecastquery.{region}.amazonaws.com host, and handling the X-Amz-Target action dispatch plus AWS retries yourself. Through Jentic you install once, import Forecast Query from the API Directory, store the AWS access keys once, and your agent calls it.
- **Permission scoping:** Forecast Query dispatches its actions through a single endpoint with the operation named in the request, so scope the agent to the operations it needs, such as querying a forecast or a what-if forecast. Any operation you do not add stays out of the allowed set.
- **Credential handling:** Your AWS access keys for Forecast Query are stored once, encrypted, by your own Jentic One instance and injected at execution time when the request is signed. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get the demand forecast for a SKU' or 'query a what-if forecast', and Jentic returns the matching Forecast Query operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Amazon SageMaker** — General ML platform for training and serving forecasting models
- **AWS Lambda** — Wraps Forecast queries inside event-driven workflows
- **Amazon EventBridge** — Schedules Forecast queries on a recurring basis

## FAQ

### Why is there no official OpenAPI spec for Amazon Forecast Query Service?

AWS does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Amazon Forecast Query Service via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Amazon Forecast Query Service use?

Forecast Query uses AWS Signature Version 4 request signing. Through Jentic, AWS access keys are stored encrypted in the vault and signing happens server-side, so the agent never sees the raw secret access key.

### Can I retrieve quantile forecasts with this API?

Yes. QueryForecast returns predictions including the quantiles configured on the underlying predictor (commonly p10, p50, and p90). Each quantile arrives as a separate timestamped series in the response.

### What are the rate limits for the Amazon Forecast Query Service?

AWS applies per-account, per-region throttling on the Forecast runtime. Use exponential backoff on ThrottlingException responses; AWS does not publish exact TPS numbers in the spec.

### How do I run a what-if scenario through Jentic?

Search Jentic for what if forecast, load the QueryWhatIfForecast schema, and execute it with the what-if forecast ARN and an item filter. Jentic returns baseline and scenario series side by side.

### Does this API train Forecast predictors?

No. Training, evaluation, and deployment live in the separate Amazon Forecast control plane. This service only serves queries against forecasts that have already been generated.

### Can I limit what my agent is allowed to do with the Amazon Forecast Query Service?

Yes. Because you run Jentic One yourself, your own rules decide which operations the agent may call, and the Forecast Query Service dispatches every action through a single signed endpoint keyed by the operation name. You add only the operations the agent needs, such as QueryForecast for point and quantile predictions or QueryWhatIfForecast for baseline-versus-scenario series, and any operation you leave out stays outside the allowed set. Your AWS access keys are held by your own instance and injected at signing time, so the agent never handles the raw credentials.