How to Import CSV into Clay: Step-by-Step Table Setup

Clay tables are capped at 50,000 rows across all standard plans, while trial accounts are restricted to just 100 rows per table [Clay Documentation]. This structural boundary determines how operations teams structure their lead databases. When datasets exceed the 50,000-row limit, imports stop automatically without returning an error. Enterprise users must run Bulk Enrichment jobs to scale calculations up to 25 million records without filling standard table rows. Basic text columns are limited to a cell size of 8KB of data per cell, and action columns have a 200KB limit.

Before loading raw lead data, formatting the CSV is necessary to prevent mapping errors. Ensure the file uses standard text encoding and standard comma delimiters. If the dataset contains nested JSON objects, commas inside cells can cause spreadsheet engines to misinterpret column boundaries. Clean the CSV by flattening nested structures or enclosing text fields in quotation marks before beginning the upload process. When mapping fields during high-volume imports, operations managers should also check the CSV headers for trailing spaces. A single trailing space in a header name can cause Clay's automation parser to create a duplicate column instead of mapping to the intended target column.

To import a CSV into a new Clay table and map the fields, perform these UI steps:

1. Open your Clay workspace dashboard and click the + Create new button.
2. Search for the CSV import option and click it to open the file selector.
3. Drag and drop your target CSV file, or select Browse Files to locate the file.
4. Select Create new table as the target destination.
5. Map each CSV header to a corresponding Clay column type, such as Text, Integer, or URL.
6. Select Save and don't run under the row settings to load data without triggering immediate credit spend.

Clay automatically reads the first row of your CSV to suggest initial mapping configurations. However, manual verification is critical. Verify that identifiers like company domains are mapped to the URL format rather than basic text. Correct column mapping ensures that subsequent waterfall enrichments recognize your inputs. If Clay detects column headers that do not match default datatypes, it defaults them to Text. You must manually override these types during the import preview to prevent downstream integration failures. If your list contains custom field parameters that are not recognized by default, you can create custom columns on the fly during this preview step. Pre-configuring these variables avoids the need to clean or format columns after the import is finalized, allowing your waterfall steps to run immediately once triggered.

Adding new records to an existing table follows a slightly different UI path. Instead of creating a new grid, you merge the new CSV list with your existing rows. This prevents duplicate setups and lets you reuse existing enrichment configurations.

To append a CSV list to an existing Clay table, perform the following steps:

1. Open the existing table in your Clay workspace.
2. Click the Tools button in the upper-right corner of the interface.
3. Select Import and choose Import from CSV from the option list.
4. Upload your target CSV file and select the destination.
5. Map your CSV columns to the existing table fields.
6. Configure the run settings to determine how rows are executed.

Managing the clay csv run rows settings is critical for keeping operational costs under control. When importing a new list, you are presented with two choices: 'Save and run rows' or 'Save and don't run'. Selecting 'Save and run rows' immediately triggers all active waterfall enrichments for the newly imported data. If your workflow contains multiple enrichment steps, this can quickly deplete your actions budget. Selecting 'Save and don't run' imports the data and puts the rows in a queued state. This allows operations managers to audit the imported data, verify column mapping, and execute enrichment waterfalls manually or in smaller batches. For teams managing continuous lead inflows, keeping run row settings on 'Save and don't run' is the standard gate. It allows you to run double-enrichment sequences only on verified companies, preventing your credit balance from being spent on invalid or low-quality data rows.

When operations teams import CSV lists into Clay that contain links to documents (such as PDF proposals, event registration images, or contract drafts), they often encounter parsing gaps. Many guides fail to explain how remote file URLs in CSVs are parsed by AI enrichment columns, which is a major source of workflow failure. When you configure an AI enrichment column (using models like Claude or GPT models) to read file URLs directly from a Clay table, the AI model attempts to fetch the file contents. If the URL points to Google Drive or Dropbox, it does not lead to a raw file. Instead, it loads an interactive HTML preview page that requires authentication. The AI column fails to parse this page, returning HTML errors and consuming costly API credits without extracting any useful data.

Fast.io resolves these parsing challenges by acting as the secure, direct storage layer for your files. Instead of using complex OAuth redirects, Fast.io generates clean, persistent download links for files stored in your workspace. When these links are placed in your CSV and imported into Clay, the AI enrichment columns can fetch and parse the raw documents directly without facing login gates or landing pages.

Alternatively, teams can bypass Clay's expensive URL parsing altogether by using Fast.io's native Metadata Views. Metadata Views turn documents into a live, queryable database inside your workspace. Instead of importing file URLs into Clay and paying for external AI scraping, you can upload PDFs, spreadsheets, and images directly to Fast.io. You specify the fields you want to extract in natural language (such as invoice numbers, signing dates, or total amounts), and Fast.io's AI designs a typed schema, processes the files, and populates a structured spreadsheet. You can then download this pre-processed CSV and import it into Clay, ensuring your columns are perfectly formatted and ready for outreach. Learn more about document processing on the Metadata Views product page.

Store and Query Clay Datasets in Shared Agent Workspaces

Connect your outbound lists to persistent storage with version control, automatic RAG indexing, and MCP tool access. Start your 14-day free trial today.

Start 14-Day Trial

For developer teams building custom outbound campaigns, Fast.io serves as an intelligent repository rather than just a storage folder. Modern development often involves collaborative workflows where autonomous agents and human developers interact. By using Fast.io's Model Context Protocol server, developers can connect their local agent setups (built on frameworks like Mastra or OpenClaw) directly to the shared workspace. The MCP server supports Streamable HTTP access at /mcp and legacy Server-Sent Events at /sse. This allows agents to read file versions, write processed CSV files, and coordinate datasets without local storage limits. More details on setting up these systems can be found in the MCP documentation.

Fast.io keeps all documents version-controlled. When multiple agents or humans update a lead sheet, maintaining file integrity is difficult. Fast.io maintains a detailed, per-file version history. If an agent writes an updated list or formats a column incorrectly, you can restore previous versions immediately. All activity is logged in the append-only audit log, which provides an immutable record of which user or agent modified a file.

Additionally, developers can configure webhooks on the Fast.io side. When a new Clay CSV is uploaded, a webhook triggers a downstream server or agent loop to process the leads, eliminating the need to poll the storage directory.

When the lead database is finalized and enrichment loops are complete, the agent can hand off the entire workspace to the human GTM lead. The agent account can transfer organization ownership directly to the client or sales manager. Fast.io has no permanent free plans or free agent tiers. Creating a user account is free, but executing real GTM work requires a paid organization subscription. Every organization starts with a 14-day trial that requires a credit card. Paid subscription plans are designed for different scales: Starter is priced at $29 per month, Business is $99 per month, and Growth is $299 per month. This ownership handoff ensures that humans maintain control over GTM workflows, access logs, and billing. Explore our tiers on the pricing page and review agent workflows on the storage for agents portal.