Cost & Usage Reports (CUR)

Cost & Usage Reports (CUR) is a billing-only connection method for organisations where granting CostLens direct AWS API access is not permitted due to security or compliance requirements. Instead of an IAM role with ReadOnlyAccess, CostLens reads billing exports delivered to an S3 bucket — requiring only a narrowly scoped S3 read policy.

When to use CUR#

What you get with CUR#

How it works#

Step 1 — Enable Cost & Usage Reports in AWS#

1. Sign in to the AWS Console and go to Billing & Cost Management → Cost & Usage Reports.
2. Click Create report.
3. Fill in the report settings:

4. Click Next to configure the S3 delivery.
5. Create a new S3 bucket or select an existing one. Enter a prefix (e.g., costlens/). AWS will automatically add the required bucket policy allowing the billing service to write files.
6. Click Next → Review and Complete.

Step 2 — Create an S3 read-only IAM role for CostLens#

CostLens needs an IAM role in your account to read the CUR files from S3. This role requires only two S3 permissions — no other AWS access is granted.

2a — Create the role#

1. In AWS IAM → Roles → Create role, select AWS account as the trusted entity type.
2. Choose Another AWS account and enter the CostLens AWS account ID (shown in the connect dialog inside CostLens).
3. Check Require external ID and paste the External ID displayed in the CostLens connect dialog.
4. Click Next.

2b — Attach an S3 read-only inline policy#

Instead of using a managed policy, create an inline policy scoped to your specific CUR bucket:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CostlensCURRead",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::YOUR-CUR-BUCKET-NAME",
        "arn:aws:s3:::YOUR-CUR-BUCKET-NAME/*"
      ]
    }
  ]
}

Replace YOUR-CUR-BUCKET-NAME with the name of the S3 bucket where AWS delivers your CUR files.

2c — Name the role and create it#

Name the role CostLensCURReadOnly (or any name that fits your naming convention). Click Create role.

Copy the Role ARN — you will paste it into CostLens in the next step.

Step 3 — Connect in CostLens#

1. In CostLens, go to Accounts → Add Account.
2. Under the Billing Only section, click Cost & Usage Reports.
3. Fill in the form:

4. Click Test S3 Access to verify CostLens can read the bucket. This must pass before you can connect.
5. Click Connect Account.

Step 4 — What to expect#

After connecting:

• CostLens sets the account status to Billing Only and immediately attempts to find existing CUR files in the bucket.
• If AWS has already delivered at least one billing period, billing data appears in the dashboard within a few minutes.
• If no CUR files exist yet (you just enabled the report), data will appear after AWS delivers the first file — typically within 24 hours.
• CostLens processes CUR data daily at 05:00 UTC, covering the 3 most-recent billing periods on each run to catch up if files were missed.

Consolidated CUR (multiple AWS accounts in one report)#

If you are using AWS Organizations and have set up a management account CUR that covers all linked member accounts, CostLens handles this automatically.

When CostLens ingests a consolidated CUR, it filters each row by the lineItem/UsageAccountId field and only imports costs for the specific AWS account ID associated with the CostLens account. This means:

• You can connect multiple CostLens accounts, each pointing to the same consolidated CUR bucket but with a different AWS account ID.
• Each account's billing dashboard shows only its own costs — no mixing between member accounts.

How to set this up:

1. Create the CUR on the management account — it will contain billing data for all linked accounts.
2. In CostLens, create a separate account entry for each member account you want to analyse.
3. For each account, use the same CUR bucket and prefix but enter the correct member account's IAM role ARN (the role must exist in the member account, not the management account).

Switching an existing account from Cost Explorer to CUR#

If you have an IAM-connected account where Cost Explorer is not enabled, CostLens automatically falls back to CUR billing sync when:

• The account has a cur_bucket configured (via the Billing Data Source panel in Account Settings), and
• The billing sync encounters a "Cost Explorer not enabled" error.

To configure CUR for an existing account:

1. Open the Accounts page and expand the account card.
2. In the Billing Data Source section, click Configure CUR.
3. Enter your S3 bucket, prefix, and region, then test and save.

Once configured, CostLens will automatically use CUR instead of Cost Explorer for billing data on the next sync.

Billing source indicator#

On the Accounts page, each account card shows a small badge on the right side:

Troubleshooting#