canonical: https://jentic.com/apis/amazonaws.com/personalize-runtime

# AWS Amazon Personalize Runtime

Jentic publishes the only available OpenAPI specification for Amazon Personalize Runtime, keeping it validated and agent-ready. Amazon Personalize Runtime serves real-time personalized recommendations and re-ranked item lists from machine learning models trained in Amazon Personalize. The service exposes two inference endpoints that consume a deployed campaign or recommender ARN and return ranked itemIds tailored to a specific user, context, or input list. It is designed for live serving paths inside e-commerce, media, and content discovery applications where models built in Personalize need to be queried at request time.

## For AI agents

Fetch personalized item recommendations and rerank candidate lists for a specific user from a trained Amazon Personalize model.

## Scope

Does not train models, manage datasets, or create campaigns - use for real-time inference against an already-deployed Amazon Personalize campaign or recommender only.

## Capabilities

- Return ranked item recommendations for a userId from a deployed Personalize campaign or recommender
- Rerank a candidate inputList of itemIds against a personalization campaign for a given user
- Pass real-time context features (deviceType, location, weather) that influence recommendation scoring
- Filter recommendations using a Personalize filter ARN with dynamic filterValues such as exclude-purchased
- Retrieve recommendation metadata columns alongside itemIds when metadataColumns is configured on the recommender
- Promote specific items into the response slate using promotion rules attached to the request

## Use cases

### Real-Time E-Commerce Recommendations

Power product carousels and 'recommended for you' modules on storefront pages by calling a deployed Personalize campaign at request time. The Runtime API takes a userId and campaignArn and returns a ranked list of itemIds with optional metadata columns, so the storefront can render personalized slates in tens of milliseconds. Use filters to exclude out-of-stock or already-purchased items without retraining the model.

Example prompt: Call GetRecommendations with campaignArn for the homepage campaign, userId 'shopper-7842', numResults 12, and filterArn excluding purchased items, then return the ranked itemIds

### Search Result Reranking

Take an existing list of candidate items from a search engine or content index and rerank it per user using a Personalized-Ranking recipe. The PersonalizeRanking endpoint accepts the inputList plus userId and returns the same items reordered by predicted relevance, with optional context metadata. This lets teams keep their primary search infrastructure and layer personalization on top.

Example prompt: Call GetPersonalizedRanking with the campaignArn for the personalized-ranking campaign, userId 'user-991', and an inputList of 50 candidate articleIds, and return the reranked order

### Contextual Content Discovery

Serve different recommendations based on real-time signals like deviceType, location, or time of day by passing a context map into each request. Amazon Personalize Runtime applies the context to the trained model so a mobile evening session and a desktop weekday session can produce distinct slates from the same campaign. Useful for media catalogues, news apps, and travel discovery.

Example prompt: Call GetRecommendations for userId 'reader-44' with context {'DEVICE': 'mobile', 'TIME_OF_DAY': 'evening'} and numResults 20

### AI Agent Recommendation Tool via Jentic

An AI shopping or content agent uses Jentic to discover the Personalize Runtime operation, load its input schema, and call it with a userId pulled from session state. The agent never holds the AWS credentials directly: Jentic injects SigV4-signed requests using the configured AWS access key from its vault. The agent receives a ranked itemIds list and can pass the result downstream to a product-detail tool or a response composer.

Example prompt: Use Jentic to search 'get personalized recommendations for a user', load GetRecommendations, and execute it with the user's session id and the homepage campaignArn

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /recommendations | Get a ranked list of recommended itemIds for a user from a campaign or recommender |
| POST | /personalize-ranking | Rerank an inputList of itemIds for a specific user against a personalized-ranking campaign |

## Key resources

- **Recommendations** — Returns a ranked list of itemIds for a user from a deployed campaign or recommender
- **PersonalizedRanking** — Reranks a supplied inputList of itemIds for a specific user against a personalized-ranking campaign

## Why Jentic

- **Setup:** Wiring Personalize Runtime by hand means implementing AWS SigV4 signing, targeting the regional host such as personalize-runtime.us-east-1.amazonaws.com, and handling ProvisionedThroughputExceededException with your own backoff on the serving path. Through Jentic you install once, import Amazon Personalize Runtime from the API Directory, store the AWS access key once, and your agent calls it.
- **Permission scoping:** Personalize Runtime passes the campaign or recommender ARN in the request body rather than the URL path, so scoping is by operation, not by path prefix. This API exposes only two read operations, so you can limit the agent to GetRecommendations, GetPersonalizedRanking, or both, and neither writes back to the model.
- **Credential handling:** Your AWS access key is stored once, encrypted, by your own Jentic One instance and used to sign each Personalize Runtime request with SigV4 at execution time. The raw secret never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get personalized recommendations for a user' or 'rerank a candidate list for a reader', and Jentic returns the matching Personalize Runtime operation such as GetRecommendations with its input schema so the agent calls the right endpoint without browsing the AWS reference.

## Related APIs

- **Amazon SageMaker** — Build, train and host custom recommendation or ranking models when Personalize's recipes are not flexible enough
- **Amazon Kendra** — Pair enterprise semantic search with personalized reranking of result sets
- **Amazon Comprehend** — Generate text features and topic signals to enrich items before serving recommendations

## FAQ

### Why is there no official OpenAPI spec for Amazon Personalize Runtime?

AWS does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Amazon Personalize Runtime 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 Personalize Runtime API use?

The API uses AWS SigV4 HMAC request signing with an AWS access key ID and secret access key. Through Jentic, AWS credentials are stored in your Jentic One instance and SigV4 signatures are generated per call, so the agent never sees raw secret keys.

### Can I rerank an existing list of items with this API?

Yes. Call POST /personalize-ranking with a campaignArn pointing to a campaign trained on a personalized-ranking recipe, a userId, and an inputList of itemIds. The response returns the same items reordered by predicted relevance for that user.

### What are the rate limits for Amazon Personalize Runtime?

Personalize Runtime applies per-region transactions-per-second quotas at the campaign level rather than fixed API rate limits. The default minProvisionedTPS on a campaign is 1; raise it on the campaign to support higher request rates. Throttled calls return a ProvisionedThroughputExceededException.

### How do I get personalized recommendations for a user through Jentic?

Search Jentic for 'get personalized recommendations for a user', load the GetRecommendations operation, and execute it with your campaignArn and userId. The Jentic SDK handles SigV4 signing using credentials stored in the vault. Install with pip install jentic.

### Is Amazon Personalize Runtime free?

No. Personalize Runtime charges per recommendation request beyond the free tier and you also pay for the underlying campaign or recommender's provisioned TPS. See the AWS Personalize pricing page for the current per-request and per-TPS-hour rates.

### Can I limit what my agent is allowed to do with the AWS Personalize Runtime API?

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use, and this API exposes only two read operations, so you can allow just GetRecommendations, just GetPersonalizedRanking, or both. Scoping is done per operation rather than by URL path, since the campaign or recommender ARN is passed in the request body. Neither operation writes back to the model, so the agent can only fetch or rerank recommendations, never retrain or modify a campaign.