> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bigspin.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Upload AI Conversation Transcripts to a Project
> Import transcripts into a Bigspin project using CSV, TSV, JSON, JSONL, or Parquet files. Learn the required schema and how to structure your data.
Uploading transcript files is the fastest way to get conversation data into a Bigspin project. You can upload files when you first create a project, or add more transcripts to an existing project at any time. Bigspin supports several common file formats and parses them automatically so you don't need to do any pre-processing before uploading.
## Supported file formats
Bigspin accepts the following formats:
| Format | Extension |
| -------------------------------- | ---------- |
| Comma-separated values | `.csv` |
| Tab-separated values | `.tsv` |
| JSON array or object | `.json` |
| JSON Lines (one object per line) | `.jsonl` |
| Apache Parquet | `.parquet` |
The maximum file size per upload is **500 MB**. If your dataset exceeds this limit, split it into multiple files and upload them together — Bigspin accepts multiple files in a single upload.
## Expected schemas
Bigspin is flexible about column and field naming, but each transcript must contain an identifier and the conversation content.
Each row in the file represents one transcript. The following columns are recognized:
**Required:**
* `id` — a unique identifier for the transcript
* `conversation` (or `messages`, `turns`, or `transcript`) — the conversation content
**Optional:**
* `name` — a human-readable label for the transcript
* `timestamp` (or `started_at` or `created_at`) — when the conversation took place (ISO 8601 format recommended)
```csv theme={null}
id,name,conversation,started_at
t1,Support chat,"[{""role"":""user"",""content"":""Hi""}]",2026-03-23T04:59:52Z
```
Each object represents one transcript. The following fields are recognized:
**Required:**
* `id` — a unique identifier for the transcript
* `turns` — an array of turn objects, each with `role` and `content`
**Optional:**
* `name` — a human-readable label for the transcript
* `started_at` (or `created_at`) — when the conversation took place
**Valid roles for turns:** `user`, `assistant`, `human_agent`, `system`, `tool`
**Example JSONL (one object per line):**
```jsonl theme={null}
{"id": "t1", "turns": [{"role": "user", "content": "Hi"}, {"role": "assistant", "content": "Hello"}], "started_at": "2026-03-23T04:59:52Z"}
{"id": "t2", "turns": [{"role": "user", "content": "What can you do?"}, {"role": "assistant", "content": "I can help with many things."}], "started_at": "2026-03-23T05:12:00Z"}
```
**Example JSON array:**
```json theme={null}
[
{
"id": "t1",
"turns": [
{"role": "user", "content": "Hi"},
{"role": "assistant", "content": "Hello"}
],
"started_at": "2026-03-23T04:59:52Z"
}
]
```
Parquet files follow the same column conventions as CSV/TSV. Bigspin reads the schema from the file and maps recognized column names automatically.
**Required columns:** `id` and one of `conversation`, `messages`, `turns`, or `transcript`
**Optional columns:** `name`, `timestamp`, `started_at`, or `created_at`
## How to upload transcripts
You can upload transcripts when creating a new project or from inside an existing project.
### During project creation
From the Projects dashboard, click **Create Project**.
In the **Upload transcripts** section of the dialog, drag your files onto the drop zone, or click the drop zone to open a file picker.
You can select multiple files at once. Files that fail validation (wrong format or over 500 MB) are rejected individually — valid files in the same selection are still added.
Each added file appears below the drop zone with its name and size. Click the **×** next to a file to remove it before submitting.
Click **Create Project**. Bigspin uploads and processes all selected files and takes you to the import progress screen.
### In an existing project
Click the project card on the Projects dashboard to open it.
Inside the project, click the **Upload** or import button to open the file upload interface.
Drag files onto the drop zone or click to browse. Bigspin begins processing as soon as the upload completes.
## What happens after upload
Once you upload files, Bigspin:
1. Validates each file's format and size
2. Parses the transcripts according to the detected schema
3. Ingests the conversations into your project
4. Makes them available for analysis and reporting
If a file contains columns or fields that Bigspin doesn't recognize, it ignores the unknown fields and processes everything else. Check the import progress screen for any parsing warnings.
## Transcript Filters (with a connected data source)
If your workspace has a data source integration (such as LangSmith) connected, a **Transcript Filters** section appears in the Create Project dialog. Filters let you scope your project to only include transcripts whose metadata matches specific key/value criteria — for example, only traces tagged with a particular environment or user segment.
As you add filter conditions, Bigspin shows a live **preview count** of how many transcripts currently match. Filters are applied at the subscription level and continue to be enforced on new traces as they sync in.
Transcript Filters are only available when a data source integration is connected to your workspace. See [Connect Data Sources](/projects/connect-data-sources) for setup instructions.