> For the complete documentation index, see [llms.txt](https://docs.finout.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.finout.io/telemetry-integrations/telemetry/s3-csv-telemetry.md).

# S3 CSV Telemetry

Telemetries allow you to take business or usage data - like API calls, active users, bytes transferred, or queries run - and use them to power cost allocation, unit economics, and shared cost breakdowns.

S3 CSV telemetry lets you feed that data into Finout through CSV files uploaded to a bucket on S3.

Once connected, Finout reads your CSV files daily, maps the date and metric columns you define, and makes the data available across [Virtual Tags](https://docs.finout.io/user-guide/inform/virtual-tags), [Cost Centers](https://docs.finout.io/settings/cost-centers), and [dashboards](https://docs.finout.io/user-guide/visualize/dashboards).

***

### Prerequisites

Before you start, make sure you have:

* An S3 bucket with CSV files already exported to it (see CSV format requirements below)
* An S3 endpoint configured in Finout, or the ability to create one during this flow (see Set up an S3 Endpoint below)
* Telemetry management permission in Finout

***

### CSV format requirements

Your CSV files must include exactly three types of columns:

<table><thead><tr><th width="131.18359375">Column type</th><th width="88.7109375">Count</th><th width="102.8203125">Required</th><th width="216.578125">Purpose</th><th>Format</th></tr></thead><tbody><tr><td><strong>Date</strong></td><td>1</td><td><mark style="color:$success;"><strong>Yes</strong></mark></td><td>One row per date per dimension combination</td><td>See supported formats below</td></tr><tr><td><strong>Metric</strong></td><td>1</td><td><mark style="color:$success;"><strong>Yes</strong></mark></td><td>The numeric value for that date and dimension</td><td>Positive number</td></tr><tr><td><strong>Metadata (dimensions)</strong></td><td>0–10</td><td><mark style="color:red;"><strong>No</strong></mark></td><td>Attributes to filter and group telemetry (e.g., team, environment, feature)</td><td>Any string</td></tr></tbody></table>

**Supported date formats:**

* `yyyy-MM-dd`
* `yyyy/MM/dd`
* `yyyy/M/d`
* `MM/d/yyyy`
* `yyyy-M-d`
* `yyyy-MM-dd'T'00:00:00'Z`

{% hint style="info" %}
Column headers must not contain spaces. The metric column name becomes the telemetry identifier in Finout — choose it carefully, as it cannot be changed after creation.
{% endhint %}

**Example CSV:**

```csv
"date","teamname","bytes"
"2022-06-07","Servers","12.12"
"2022-06-07","Storage","6.22"
"2022-06-08","Network","0.05"
```

In this example: `date` is the date column, `teamname` is a metadata dimension, and `bytes` is the metric.

***

### Set up an S3 endpoint

Finout reads your CSV files through an S3 endpoint — a configured connection to an S3 bucket that grants Finout read-only access.&#x20;

{% hint style="warning" %}
If you already have an S3 endpoint configured in Finout, skip to Create an S3 CSV telemetry.
{% endhint %}

To set up a new S3 endpoint:

1. **Navigate** to **Settings > Endpoints**.
2. **Click** **Add Endpoint**, then select **Amazon S3**.
3. Under **Bucket Access**, select **Read Only**.
4. **Copy** the External ID shown on screen.
5. In AWS IAM, [create a new cross-account role](https://console.aws.amazon.com/iam/home?region=us-east-1#/roles$new?step=type\&roleType=crossAccount):&#x20;
   1. Enter the **AWS Account ID** associated with your S3 bucket.
   2. Enable **Require external ID** and paste the External ID from Finout.
   3. Click **Next** through to the review screen.
   4. Name the role `FinoutMetricsReadOnlyRole` and create it.
   5. Open the newly created role, copy the **Role ARN**, and paste it back into Finout.
   6. In the role, **click Add permissions > Create inline policy**.
   7. Select **JSON** and insert the following policy. Replace `<BUCKET_NAME>` with your bucket name:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["tag:GetTagKeys"],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": ["s3:Get*", "s3:List*"],
      "Resource": "arn:aws:s3:::<BUCKET_NAME>/*"
    },
    {
      "Effect": "Allow",
      "Action": ["s3:Get*", "s3:List*"],
      "Resource": "arn:aws:s3:::<BUCKET_NAME>"
    }
  ]
}
```

9. Name the policy `finout-access-policy_telemetry_export` (or a name of your choosing) and save it.
10. Back in Finout, fill in the endpoint details:
    * **Endpoint Name** and optional description
    * **Role ARN**
    * **Bucket Name**
    * **S3 Path Prefix** (optional — the folder path within the bucket)
    * **Region**
11. **Click** **Test Endpoint** to verify the connection.
12. **Click** **Add Endpoint**.

***

### Create an S3 CSV telemetry

1. **Navigate** to **Settings > Telemetry**.
2. **Click** **Add Telemetry** and select **S3 CSV**.
3. **Select an S3 endpoint** from the list of configured endpoints.
4. **Enter a prefix** to identify which CSV files in the bucket belong to this telemetry (required).<br>

   <figure><img src="/files/YHynNdUyn9qxlgxCLdN0" alt=""><figcaption></figcaption></figure>
5. **Enter a telemetry name** (the display name shown in Finout).
6. Finout fetches a sample of your CSV and displays 10 rows from recent dates. Review the data to confirm you're pointing at the right files.<br>

   <figure><img src="/files/lrg13MMquTjZPnSWAc3b" alt=""><figcaption></figcaption></figure>
7. **Select the date column** — one column only.
8. **Select the date format** that matches your file from the list of supported formats. Finout validates that the column parses correctly and blocks progress if it does not.
9. **Select the metadata columns (dimensions)** you want to include. You can include up to 10. Deselect any columns you don't need.

{% hint style="info" %}
By default, no metadata columns are selected. Select the ones you want to use as dimensions in cost allocation and filtering.
{% endhint %}

10. **Select the metric column** — one column only. This becomes the telemetry identifier in Finout.
11. Review the full configuration summary: endpoint, prefix, telemetry name, date column and format, selected dimensions, and metric.<br>

    <figure><img src="/files/MOkrQzG7NogfShC1kE5U" alt=""><figcaption></figcaption></figure>
12. **Click** **Create Telemetry**.

**Result:** The telemetry is created with **Active** status and appears immediately in the Telemetries table under **Settings > Telemetries**. Finout begins ingesting data from the next daily sync.

***

### What's next

* Use your new telemetry in [shared cost reallocation](https://docs.finout.io/user-guide/inform/shared-cost-reallocation/how-to-use-shared-cost-reallocation)
* Build unit economics [dashboards](https://docs.finout.io/user-guide/visualize/dashboards) that bring cloud cost and business metrics together
* Manage or deactivate telemetries from **Settings > Telemetries**


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.finout.io/telemetry-integrations/telemetry/s3-csv-telemetry.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.