canonical: https://jentic.com/apis/amazonaws.com/performance-insights

# AWS Performance Insights

Jentic publishes the only available OpenAPI specification for AWS Performance Insights, keeping it validated and agent-ready. AWS Performance Insights is a database performance monitoring service that visualizes load on Amazon RDS, Aurora, and DocumentDB instances and lets you slice it by SQL, host, user, or wait event. The API exposes six query operations to retrieve dimension keys, time-series resource metrics, and metadata about which dimensions and metrics are available for a given DB engine. It is the programmatic surface behind the Performance Insights console for engineers who want to pull DB load data into their own dashboards, anomaly detection pipelines, or incident workflows.

## For AI agents

Query database load and wait-event data from Amazon RDS and Aurora instances by dimension, slice, and time range.

## Scope

Does not modify database configuration, kill sessions, or run SQL - use for read-only Performance Insights load and metric queries on RDS, Aurora, and DocumentDB only.

## Capabilities

- Retrieve top dimension keys (SQL, host, user, wait event) contributing to DB load over a time window
- Pull time-series resource metrics like db.load.avg and db.SQL.tokenized for an RDS or Aurora instance
- Get detailed dimension metadata including full SQL text and execution plan for a specific dimension key
- List the metrics available for a given Performance Insights resource
- Discover which dimensions can be queried for a database engine and metric combination
- Read resource metadata such as feature support flags for a Performance Insights identifier

## Use cases

### Slow-Query Investigation

Identify the SQL statements driving load on an Amazon RDS or Aurora instance during a slow-down. DescribeDimensionKeys returns the top db.sql_tokenized dimension keys ranked by db.load.avg over a time window, and GetDimensionKeyDetails fetches the full SQL text for any key. Engineers can build a 'top SQL during incident' view without opening the AWS console.

Example prompt: Call DescribeDimensionKeys for the RDS resource ARN with Metric 'db.load.avg', GroupBy db.sql_tokenized, StartTime 30 minutes ago, and EndTime now, then call GetDimensionKeyDetails on the top key to retrieve full SQL text

### Wait-Event Analysis

Diagnose contention by grouping DB load by wait event over an incident window. DescribeDimensionKeys with GroupBy db.wait_event returns ranked wait events such as IO:DataFileRead or Lock:transactionid, letting an engineer or agent reason about whether the bottleneck is IO, locking, or CPU. Pair with GetResourceMetrics for the same window to see the load envelope.

Example prompt: Call DescribeDimensionKeys with GroupBy db.wait_event for the RDS resource over the last 60 minutes and return the top 10 wait events by db.load.avg

### Custom DB Load Dashboards

Pull Performance Insights time-series into a custom dashboard or data warehouse. GetResourceMetrics returns db.load.avg and other metrics at a configurable PeriodInSeconds, optionally grouped by dimension. Teams who already centralize observability outside CloudWatch can ingest these series alongside their other DB telemetry for unified alerting.

Example prompt: Call GetResourceMetrics for the RDS resource with MetricQueries [{Metric: 'db.load.avg'}], StartTime 24 hours ago, EndTime now, and PeriodInSeconds 300

### AI Agent DB Health Tool via Jentic

An incident-response agent uses Jentic to discover Performance Insights operations, load their schemas, and call them when a paged engineer asks 'what's wrong with the DB right now'. Jentic stores the AWS access key in its vault and signs each request with SigV4, so the agent can return ranked top-SQL and wait-event summaries without ever holding raw AWS credentials.

Example prompt: Use Jentic to search 'find top sql by load on rds', load DescribeDimensionKeys, and execute it for the affected RDS ARN with the last 30 minutes as the time range

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /#X-Amz-Target=PerformanceInsightsv20180227.DescribeDimensionKeys | Top dimension keys for a metric grouped by SQL, host, user, or wait event |
| POST | /#X-Amz-Target=PerformanceInsightsv20180227.GetResourceMetrics | Time-series values for Performance Insights metrics on a resource |
| POST | /#X-Amz-Target=PerformanceInsightsv20180227.GetDimensionKeyDetails | Full detail for a dimension key, including full SQL text |
| POST | /#X-Amz-Target=PerformanceInsightsv20180227.ListAvailableResourceMetrics | List metrics available for a resource |
| POST | /#X-Amz-Target=PerformanceInsightsv20180227.ListAvailableResourceDimensions | List dimensions available for a resource and metric |
| POST | /#X-Amz-Target=PerformanceInsightsv20180227.GetResourceMetadata | Resource metadata and feature support flags |

## Key resources

- **DimensionKeys** — Top contributing keys for a metric, grouped by dimension such as SQL, host, or wait event
- **DimensionKeyDetails** — Full detail for a single dimension key, including full SQL text where applicable
- **ResourceMetrics** — Time-series values for one or more Performance Insights metrics
- **ResourceMetadata** — Feature support and metadata for a Performance Insights resource
- **AvailableResourceMetrics** — Metrics queryable for a given resource and metric type
- **AvailableResourceDimensions** — Dimensions available to group by for a metric on a resource

## Why Jentic

- **Setup:** Wiring Performance Insights by hand means implementing AWS SigV4 signing, targeting the regional host such as pi.us-east-1.amazonaws.com, and backing off on account-level Throttling responses yourself. Through Jentic you install once, import AWS Performance Insights from the API Directory, store the AWS access key once, and your agent calls it.
- **Permission scoping:** Performance Insights carries the resource identifier and query parameters in the request body rather than the URL path, so scoping is by operation, not by path prefix. Every operation here is read-only, so you can limit the agent to the ones it needs, such as DescribeDimensionKeys and GetResourceMetrics, and none of them change database configuration.
- **Credential handling:** Your AWS access key is stored once, encrypted, by your own Jentic One instance and used to sign each Performance Insights 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 'find top sql by load on an rds instance' or 'analyze wait events on a database', and Jentic returns the matching Performance Insights operation such as DescribeDimensionKeys with its input schema so the agent calls the right endpoint without browsing the AWS reference.

## Related APIs

- **Amazon CloudWatch** — Pair Performance Insights' fine-grained DB load with CloudWatch's instance-level CPU, memory, and IO metrics
- **AWS RDS Data API** — Execute SQL surfaced by Performance Insights without managing a connection pool
- **Amazon Redshift Data API** — Run SQL and inspect query history on Redshift, which has its own performance views rather than Performance Insights

## FAQ

### Why is there no official OpenAPI spec for AWS Performance Insights?

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

Performance Insights uses AWS SigV4 HMAC request signing with an AWS access key ID and secret. Through Jentic, AWS credentials live in the vault and SigV4 signatures are produced per call so the agent never holds raw secrets.

### Can I retrieve the full SQL text behind a top dimension key?

Yes. After DescribeDimensionKeys returns a Key with a sql_tokenized dimension, call GetDimensionKeyDetails with the same identifier and dimension group to fetch the full SQL text and any redacted markers.

### Which database engines does this API support?

Performance Insights supports Amazon RDS for MySQL, MariaDB, PostgreSQL, Oracle, SQL Server, Aurora MySQL, Aurora PostgreSQL, and Amazon DocumentDB. Performance Insights must be enabled on the instance for the API to return data.

### What are the rate limits for the Performance Insights API?

Performance Insights enforces account-level request quotas per region; calls beyond the quota return a Throttling exception. AWS does not publish fixed per-second numbers, so back off and retry on Throttling responses and batch dimension queries with sensible PeriodInSeconds.

### How do I find the top SQL on an RDS instance through Jentic?

Search Jentic for 'find top sql by load on rds', load DescribeDimensionKeys, and execute it with your RDS resource identifier, Metric 'db.load.avg', and GroupBy db.sql_tokenized. Install with pip install jentic; AWS keys are read from your Jentic One instance.

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

Yes. Because you run Jentic One yourself, your own rules decide which Performance Insights operations and AWS credentials the agent may use. Scoping here is by operation rather than by URL path, since the resource identifier and query parameters travel in the request body, so you can grant only the calls the agent needs, such as DescribeDimensionKeys and GetResourceMetrics, while withholding others like GetDimensionKeyDetails or GetResourceMetadata. Every operation on this API is read-only, so none of them can change database configuration.