> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oncost.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect AWS

> Set up AWS cost collection with an IAM cross-account role

# Connect AWS

oncost collects AWS costs via the Cost and Usage Report (CUR). Setup takes about 10 minutes.

## Prerequisites

* An AWS account with billing access
* Permission to create IAM roles and S3 buckets (or an existing CUR export)

## Step 1: Enable CUR in AWS

If you don't already have a Cost and Usage Report:

1. Go to **AWS Console > Billing > Cost and Usage Reports**
2. Click **Create report**
3. Name it (e.g., `oncost-cur`)
4. Select **Include resource IDs**
5. Choose an S3 bucket for delivery (create one if needed)
6. Set **Report path prefix** to `cur/`
7. Select **Parquet** format
8. Click **Create**

AWS delivers the first CUR within 24 hours.

## Step 2: Create the IAM role

In oncost, go to **Settings > Connections > New Connection > AWS**. oncost shows you:

* The **External ID** (unique to your organization)
* The **IAM policy** to attach

Create a cross-account IAM role in AWS:

1. Go to **IAM > Roles > Create role**
2. Select **Another AWS account**
3. Enter the oncost AWS account ID shown in the connection form
4. Check **Require external ID** and paste the External ID
5. Attach the policy shown in oncost (read-only access to CUR S3 bucket and Cost Explorer API)
6. Name the role (e.g., `oncost-cost-reader`)
7. Copy the **Role ARN**

## Step 3: Complete the connection

Back in oncost:

1. Paste the **Role ARN**
2. Enter the **S3 bucket** and **report path prefix** from your CUR setup
3. Click **Test Connection** to verify access
4. Click **Save**

oncost will run its first collection within minutes. CUR data typically covers the current and previous month.

## What oncost collects

* Daily cost breakdown by service, region, account, and resource
* Usage quantities (hours, GB, requests)
* Tags applied to resources
* Line item types (usage, tax, credit, refund)

## Troubleshooting

| Issue                   | Fix                                                                                                      |
| ----------------------- | -------------------------------------------------------------------------------------------------------- |
| "Access Denied" on test | Verify the Role ARN and External ID match. Check the IAM policy allows `s3:GetObject` on the CUR bucket. |
| No data after 24 hours  | CUR delivery can take up to 24 hours. Check AWS CUR console for delivery status.                         |
| Missing tags            | Ensure **Include resource IDs** is enabled on the CUR report. Tags appear after the next CUR delivery.   |