canonical: https://jentic.com/apis/amazonaws.com/aws-athena

# AWS Amazon Athena

Amazon Athena is an interactive query service that runs standard SQL against data stored in Amazon S3 without provisioning infrastructure. It supports federated queries to other data sources, parameterised prepared statements, named saved queries, and managed workgroups for cost and access control.

## For AI agents

Use the Amazon Athena API to run SQL queries on data in Amazon S3 on AWS, with 60 operations covering the full control-plane lifecycle.

## Scope

Does not handle data ingestion, ETL, or warehouse cluster management - use for serverless SQL querying on existing data lakes only.

## Capabilities

- Submit SQL queries against S3 data using the Glue Data Catalog or a federated data source
- Track query execution status, scanned bytes, and cost per query
- Create workgroups that enforce per-team result locations and cost controls
- Save reusable named queries and parameterised prepared statements
- Run Spark notebooks against the data catalog from inside Athena
- List historical query executions for auditing and re-run

## Use cases

### Ad-hoc analytics on an S3 data lake

Run interactive SQL against terabytes of Parquet, JSON, or CSV data sitting in Amazon S3 without provisioning a warehouse. Athena reads table metadata from the Glue Data Catalog, executes the query in a serverless engine, and writes results to a configured S3 location. Teams can be productive within an hour once the catalog is in place.

Example prompt: Submit the query 'SELECT region, SUM(amount) FROM sales WHERE year = 2026 GROUP BY region' through Athena's primary workgroup and return the query execution id.

### Per-team query isolation with workgroups

Separate analyst, finance, and engineering query traffic by creating distinct workgroups, each with its own result S3 location, scanned-bytes limit, and CloudWatch metrics. Workgroup configuration enforces guardrails such as encryption requirements and per-query cost ceilings without relying on policy checks at the IAM layer alone. Setup takes minutes per workgroup.

Example prompt: Create a workgroup named 'analytics-prod' with a per-query data-scanned limit of 1 TB and a result S3 location of s3://athena-results/analytics-prod/.

### Parameterised report generation

Define prepared statements for routine report queries - for example a tenant-scoped revenue report - so applications can execute the same template with different bound parameters without re-sending the SQL text. Combined with named queries, this gives analysts a small, governed library of canonical queries.

Example prompt: Create a prepared statement named 'tenant_revenue' under workgroup 'analytics-prod' with the SQL 'SELECT month, SUM(amount) FROM sales WHERE tenant_id = ? GROUP BY month'.

### AI agent answering analytics questions through Jentic

A data agent can answer business questions on demand by searching for the Athena query intent through Jentic, loading the StartQueryExecution and GetQueryResults schemas, and executing them with scoped credentials. The agent reasons over the returned rows without ever holding raw AWS access keys. Multi-step query and result handling becomes a single agent intent.

Example prompt: Search Jentic for 'run a SQL query against data in S3', load StartQueryExecution and GetQueryResults schemas, and execute a query that returns last week's revenue by region.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /#X-Amz-Target=AmazonAthena.StartQueryExecution | Start a SQL query execution |
| POST | /#X-Amz-Target=AmazonAthena.GetQueryResults | Retrieve results for a completed query |
| POST | /#X-Amz-Target=AmazonAthena.GetQueryExecution | Describe a query execution and its status |
| POST | /#X-Amz-Target=AmazonAthena.CreateWorkGroup | Create a workgroup with cost and access controls |
| POST | /#X-Amz-Target=AmazonAthena.CreateNamedQuery | Save a named query |
| POST | /#X-Amz-Target=AmazonAthena.CreatePreparedStatement | Create a parameterised prepared statement |

## Key resources

- **Workgroups** — Isolation boundaries with separate query history, cost limits, and result locations
- **DataCatalogs** — Connections to Glue catalogs or external metastores describing tables
- **QueryExecutions** — Records of query runs with status, statistics, and result locations
- **NamedQueries** — Saved query definitions reusable across sessions
- **PreparedStatements** — Parameterised SQL templates that clients can execute with bound values
- **Notebooks** — Spark notebooks for querying data with PySpark inside Athena

## Why Jentic

- **Setup:** Wiring Amazon Athena by hand means creating IAM credentials, choosing the right regional host from athena.{region}.amazonaws.com, signing every request with AWS SigV4, and passing the X-Amz-Target action header on each call yourself. Through Jentic you install once, import Amazon Athena from the API Directory, store the AWS access key once, and your agent calls it.
- **Permission scoping:** Amazon Athena carries the query and workgroup targets in the request body rather than the URL path, so limit the agent to the operations it needs, such as StartQueryExecution, GetQueryResults, or GetQueryExecution. You choose the operations it may call, so destructive ones like deleting a workgroup or a named query are not included unless you add them.
- **Credential handling:** Your AWS access key for Amazon Athena is stored once, encrypted, by your own Jentic One instance and signed with SigV4 at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'run a SQL query against data in S3' or 'retrieve results for a completed query', and Jentic returns the matching Amazon Athena operation with its input schema so the agent calls the right endpoint without browsing the AWS service reference.

## Related APIs

- **Redshift Data API** — Redshift Data API runs SQL against Redshift clusters rather than S3 data lakes
- **EMR on EKS** — EMR on EKS runs heavyweight Spark and Hive workloads alongside Athena's interactive queries
- **Kinesis Data Analytics** — Kinesis Data Analytics runs SQL on streaming data rather than data at rest in S3

## FAQ

### What authentication does the Amazon Athena API use?

The Amazon Athena API uses AWS Signature Version 4 (HMAC) request signing with IAM-issued credentials, the same scheme as every AWS service API. Jentic's your Jentic One instance stores those AWS credentials encrypted in the vault, generates short-lived signed requests at execution time, and never passes raw access keys into the agent's context.

### Can I run a sql query on data in my s3 bucket with the Amazon Athena API?

Yes - the Amazon Athena API exposes 60 operations including the actions needed for that scenario. Use the operations listed in the key endpoints section as the starting point, then chain calls as needed for your workflow.

### What are the rate limits for the Amazon Athena API?

AWS applies per-account, per-region request rate limits to the Amazon Athena control plane. Specific limits are not encoded in the OpenAPI spec; consult the AWS service quotas console for the Amazon Athena entry, and design retries with exponential backoff to absorb throttling responses.

### How do I run a SQL query against data in S3 through Jentic?

Run pip install jentic, then call client.search('run a SQL query against data in S3') to discover the Amazon Athena operations that match. Load the schema for the chosen operation with client.load(...) and execute it with client.execute(...). Jentic handles AWS request signing automatically against the credentials stored in your Jentic One instance.

### Is the Amazon Athena API free to call?

AWS does not charge for control-plane API calls themselves on most Amazon Athena operations, but the underlying resources you create or operate (fleets, queries, deployments, and so on) incur usage charges according to the Amazon Athena pricing page. Refer to the AWS pricing page for the service to estimate cost.

### Which operations should an agent call first when working with the Amazon Athena API?

For most workflows, agents should start by listing existing resources to understand the current state, then call the create or update operation that matches the intent. The endpoints listed under Key Endpoints in the catalog give a ranked starting set.

### Can I limit what my agent is allowed to do with the Amazon Athena API?

Yes. Because you host your own Jentic One instance, you decide which Amazon Athena operations the agent can call, so you can allow only what a task needs, such as StartQueryExecution, GetQueryResults, and GetQueryExecution. Athena carries the query and workgroup targets in the request body rather than the URL path, so scoping happens at the operation level you define. Destructive actions like deleting a workgroup or a named query stay out of reach unless you explicitly add them, and the AWS credentials that sign each request are held by your instance rather than exposed to the agent.