Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.costoptix.com/llms.txt

Use this file to discover all available pages before exploring further.

Cost Optix reads cost data from AWS Cost Explorer. Cost Explorer must be enabled in your AWS account and resource-level data must be turned on for per-resource breakdowns.

​
Prerequisites

  • AWS CLI installed and configured (for key-based setup)
  • IAM permissions to create users, policies, and roles in the target account
  • Cost Explorer enabled in the target account (free tier includes basic access; resource-level queries have a per-query charge — see AWS pricing)

​
Required IAM Policy

Save the following policy as cost-optix-policy.json. This is the minimum set of permissions Cost Optix requires. 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CostExplorerAccess",
      "Effect": "Allow",
      "Action": [
        "ce:GetCostAndUsage",
        "ce:GetCostAndUsageWithResources",
        "ce:GetDimensionValues",
        "ce:GetCostForecast",
        "ce:GetReservationUtilization",
        "ce:GetSavingsPlansUtilization",
        "ce:GetSavingsPlansCoverage",
        "ce:GetRightsizingRecommendation",
        "ce:GetTags"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CloudWatchMetricsAccess",
      "Effect": "Allow",
      "Action": [
        "cloudwatch:GetMetricStatistics",
        "cloudwatch:GetMetricData",
        "cloudwatch:ListMetrics"
      ],
      "Resource": "*"
    },
    {
      "Sid": "S3AccessForReports",
      "Effect": "Allow",
      "Action": [
        "s3:ListAllMyBuckets",
        "s3:GetBucketLocation",
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Resource": "*"
    },
    {
      "Sid": "STSPermissionsCheck",
      "Effect": "Allow",
      "Action": [
        "sts:GetCallerIdentity"
      ],
      "Resource": "*"
    }
  ]
}

​
Setup: Access Keys (IAM User)

Use this method for straightforward deployments where Cost Optix does not run on AWS infrastructure.

​
Step 1 — Create a dedicated IAM user

aws iam create-user --user-name cost-optix-reader

​
Step 2 — Create and attach the policy

# Create the policy (save the returned ARN)
aws iam create-policy \
  --policy-name CostOptixReaderPolicy \
  --policy-document file://cost-optix-policy.json

# Attach to the user — replace <ACCOUNT_ID> with your 12-digit AWS account ID
aws iam attach-user-policy \
  --user-name cost-optix-reader \
  --policy-arn "arn:aws:iam::<ACCOUNT_ID>:policy/CostOptixReaderPolicy"

​
Step 3 — Create an access key

aws iam create-access-key --user-name cost-optix-reader
The SecretAccessKey is shown only once. Copy it immediately.

​
Step 4 — Enable resource-level data in Cost Explorer

IAM permissions alone are not enough for resource-level breakdowns. In the AWS Console:
  1. Go to Billing & Cost Management → Cost Explorer → Settings
  2. Enable “Resource-level data”
  3. Click Save
Data appears within 24 hours and is only available from the enable date forward. Without this setting, Cost Optix can display service-level totals but cannot drill into individual resources.

​
Step 5 — Activate Cost Allocation Tags (for Tag Explorer)

For the Tag Explorer to work, each tag key must be individually activated:
  1. Go to Billing & Cost Management → Cost Allocation Tags
  2. Select your tag keys and click Activate
This is separate from IAM permissions. Activation takes effect immediately.
Use an IAM Role when Cost Optix runs on AWS infrastructure, or when monitoring a different account from where Cost Optix is deployed.

​
Step 1 — Create the trust policy

cat > trust-policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::<TRUSTING_ACCOUNT_ID>:root" },
    "Action": "sts:AssumeRole",
    "Condition": { "StringEquals": { "sts:ExternalId": "cost-optix" } }
  }]
}
EOF
Replace <TRUSTING_ACCOUNT_ID> with the AWS account ID that runs Cost Optix.

​
Step 2 — Create the role and attach the policy

# Create the role
aws iam create-role \
  --role-name CostOptixReader \
  --assume-role-policy-document file://trust-policy.json

# Create and attach the policy (save cost-optix-policy.json from above first)
aws iam create-policy \
  --policy-name CostOptixReaderPolicy \
  --policy-document file://cost-optix-policy.json

# Attach the policy — replace <ACCOUNT_ID>
aws iam attach-role-policy \
  --role-name CostOptixReader \
  --policy-arn "arn:aws:iam::<ACCOUNT_ID>:policy/CostOptixReaderPolicy"

# Get the Role ARN to paste into Cost Optix
aws iam get-role --role-name CostOptixReader --query 'Role.Arn' --output text

​
Step 3 — Enable resource-level data and Cost Allocation Tags

Same as Steps 4–5 for the access key method above.

​
Billing Lag

AWS Cost Explorer data is typically available within 24–48 hours.
Data typeTypical availability
Daily cost totalsT+1 to T+3 days
Resource-level detailT+1 to T+3 days (requires resource-level data enabled)
Cost Allocation TagsAvailable after activation; only forward-dated

​
Enter Credentials in Cost Optix

Navigate to Organization Admin → Accounts → Add Account, select Amazon Web Services, and enter: For Access Keys:
  • Access Key ID
  • Secret Access Key
  • Default Region (Cost Explorer always uses us-east-1 internally)
For IAM Role:
  • Role ARN (e.g. arn:aws:iam::123456789012:role/CostOptixReader)
  • External ID: cost-optix

​
Troubleshooting

“AccessDeniedException” from Cost Explorer Confirm the IAM policy includes ce:GetCostAndUsage and ce:GetCostAndUsageWithResources, and that the policy is attached to the correct user or role. Resource-level data is missing Check that “Resource-level data” is enabled in Cost Explorer settings. This is a console-only toggle — there is no CLI equivalent. Data is only available from the date you enabled it. Tag Explorer returns no tags Tag keys must be individually activated in Billing & Cost Management → Cost Allocation Tags. Having tags on your EC2 or S3 resources is not enough — they must also be activated as cost allocation tags. “InvalidAccessKeyId” or signature errors Verify the Access Key ID and Secret Access Key are entered correctly and the IAM user has not been disabled or the key deactivated.