---
title: "Amazon Q"
canonical_url: "https://docs.getdx.com/connectors/amazon-q/"
md_url: "https://docs.getdx.com/connectors/amazon-q.md"
last_updated: "2026-11-13"
---

# Amazon Q
By integrating Amazon Q with DX, you can analyze Amazon Q daily usage metrics and AI assistant interactions. Please refer to the API documentation below and our [schema explorer](https://docs.getdx.com/schema/) to see what data DX imports.

## Prerequisites

To connect Amazon Q to DX, you need:

- An AWS account with Amazon Q access
- Access to AWS IAM to create a Policy and Role
- An S3 bucket configured for Amazon Q data storage

## Setup instructions

Amazon Q connections use IAM role-based authentication for secure cross-account access.

#### Step 1 - Get your External ID from DX

1. In DX, navigate to **Settings > Data connectors > Add connector > Amazon Q**
2. Copy the **External ID** displayed - you'll need this for the trust policy

#### Step 2 - Create an IAM policy for S3 access

In your AWS account, create a custom IAM policy with S3 read permissions:

1. Go to **IAM > Policies > Create policy**
2. Select the **JSON** tab and paste the following (replace `YOUR_BUCKET_NAME` with your actual bucket name):

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DXAmazonQReadOnly",
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::YOUR_BUCKET_NAME",
        "arn:aws:s3:::YOUR_BUCKET_NAME/*"
      ]
    }
  ]
}
```

3. Name the policy (e.g., `DX-AmazonQ-Policy`) and create it

#### Step 3 - Create an IAM role with trust policy

Create an IAM role that DX can assume:

1. Go to **IAM > Roles > Create role**
2. Select **Custom trust policy** and paste the following (replace `YOUR_EXTERNAL_ID_FROM_DX` with the External ID from Step 1):

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::703671904508:role/dx-datacloud"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "YOUR_EXTERNAL_ID_FROM_DX"
        }
      }
    }
  ]
}
```

3. Click **Next** and attach the policy you created in Step 2
4. Name the role (e.g., `DX-AmazonQ-Role`) and create it
5. Copy the **Role ARN** (e.g., `arn:aws:iam::123456789012:role/DX-AmazonQ-Role`)

#### Step 4 - Configure the connection in DX

Navigate to the connections page in DX and select "+ Connection" in the top right. Enter the following in the connection form:

- **Role ARN**: The ARN of the IAM role you created
- **Region**: The AWS region where your S3 bucket is located
- **Bucket Name**: The name of your S3 bucket containing Amazon Q data
- **Connection Name**: A descriptive name for this connection (e.g., "Amazon Q Production")
- **User mapping directory path**: Path to the directory containing the user mapping files (e.g., if your file is at `example/user_mapping.csv`, enter `example/`)
- **Usage metrics directory path**: Path to AWSLogs directory (e.g., if your directory is at `example/AWSLogs/`, enter `example/`)

Click "Add connection" to establish the connection.

#### User mapping CSV format

Your user mapping CSV must contain `aws_user_uuid` and `user_email` as headers.

![](https://docs.getdx.com/assets/images/connectors/amazon/user-mapping-csv.png){class="max-w-lg mx-auto"}

#### How DX ingests usage data

To ensure accurate ingestion, provide the most specific S3 directory paths possible. DX scans recursively under the configured prefixes, so broad paths can unintentionally scan irrelevant files. Do not rename the exported files—DX relies on their original filename patterns to identify the correct reports.

**User mapping**

DX lists all objects under your configured user-mapping directory prefix (including nested subdirectories) and reads every `.csv` file it finds. Each file must contain both required columns:

- `aws_user_uuid`
- `user_email`

**Usage metrics**

DX lists all objects under your configured usage-metrics directory prefix (including nested subdirectories), then selects CSV files based on filename patterns. For Amazon Q, DX selects files whose name contains `_by_user_analytic_` and ends with `.csv`.

A valid Amazon Q usage report has these columns (in addition to `UserId` and `Date`): `Chat_AICodeLines`, `CodeFix_*`, `CodeReview_*`, `Dev_*`, `DocGeneration_*`, `InlineChat_*`, `Inline_*`, `TestGeneration_*`, and `Transformation_*`.

**Best practice**

Configure narrow, tool-specific folder prefixes so only the intended files are scanned, and keep the original Amazon Q export filenames unchanged.

---

## API reference

The table below lists the specific AWS services and permissions that are used by DX.


| Service | Documentation |
|---------|---------------|
| `sts:AssumeRole` | [Link](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) |
| `s3:GetObject` | [Link](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) |
| `s3:ListBucket` | [Link](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) |


## Errors

The table below lists potential error codes when adding a connection in DX.


| Error | Description |
|----------------------|------------------------------------------------------------------------------------------------------------------|
| `invalid_credentials` | Your IAM role configuration is not valid. |
| `access_denied` | DX cannot assume the IAM role. Check the trust policy and external ID. |
| `missing_role_arn` | IAM role ARN is required for Amazon Q connections. |
| `invalid_role_arn` | The IAM role ARN format is invalid. Expected format: `arn:aws:iam::{account-id}:role/{role-name}` |
| `bucket_not_found` | The specified S3 bucket does not exist or is not accessible. |
| `no_users_found` | No users found in the user mapping CSV (provide a valid user mapping CSV with `aws_user_uuid` and `user_email` columns). |
| `no_metrics_found` | No usage metrics found in the provided directory. |
| `invalid_permissions` | Your IAM role does not have the required permissions to access S3. |
---

## Sitemap

[Overview of all docs pages](/llms.txt)
