Overview

You can view your File-Based Imports by selecting the Import Center tab on the Partners page. This page lists every import, its current state, run health, and per-file statistics, and is where you operate imports after creation.

The Import Listing page displays all import jobs and their current state. The following table lists the details that the page displays for each import:

Health Indicator

The health indicator provides an at-a-glance view of the success rate of each import run.

Stats

Stats provides a detailed view of each import run, broken down by individual file. You can track import performance over time, understand the quality of your source data, and make informed adjustments to your import configuration with the help of these stats.

To access Stats, go to Settings > Partners > Import Center. Click an import to open its details, and then select the Stats tab.

Each import run may process multiple files. The Stats table displays one row per file processed during the run, with the following details:

File Processing Rules

CleverTap applies the following rules when processing files during an import run:

• File size limit: CleverTap does not process CSV files larger than 5 GB or Parquet files larger than 1 GB, and it marks them as Failed.
• File modified during fetching from your cloud storage: If a file changes (its size in bytes changes) while CleverTap is actively fetching it, CleverTap marks the file as Failed to ensure data integrity.
• File modified after CleverTap fetches it: If a file changes in the cloud storage after CleverTap has already fetched it, CleverTap processes the version that it fetched at the time of the run. CleverTap does not reflect changes made after the fetch in that run.

Import Stats

Click a file row in the Stats table to open the detailed record view for that file. Detailed record data is available only for import runs completed within the last 30 days.

Each record in the detail pane displays the following:

You can filter the records displayed in the detail pane using the All Records dropdown. The following filter options are available:

• All Records: Displays all records processed from the file, regardless of result.
• Sync Successes: Displays only records that were successfully imported.
• Sync Fails: Displays only records that failed to import.

You can also search for a specific record using the Search identity field to look up a record by its identity or CleverTap ID.

To view the full user profile associated with a record, click the View profile icon next to the record. This is available for both user profile and event data imports.

Recommendation for Using Stats to Improve Sync

Stats works best as a feedback loop to actively improve the quality and reliability of future imports. The following are recommended ways to get the most out of Stats.

• Track health trends across runs: Review the health percentage across multiple runs to spot patterns. A consistent green health indicates a stable, well-mapped import. A declining trend often signals a change in the source file structure, unexpected values in a column, or storage bucket credentials that need updating.
• Use failed records to refine your mappings: When a run shows failed syncs, click into the file row and review the failed records in the detail pane. If the same field fails across many records, the issue is likely in how it is mapped or formatted in the source file. Addressing the root cause in the source data or remapping the field will improve health across future runs.
• Monitor file-level failures: If a file row shows a Failed status with zero records processed, the file may have exceeded the 5 GB size limit or was modified during fetching. Review your data pipeline to ensure files are fully written and within the size limit before they are picked up by CleverTap.
• Prioritize identity errors: Records without a valid identity cannot be linked to a user profile in CleverTap and will not be usable for segmentation or engagement. Resolve identity-related failures before addressing property-level errors.
• Compare runs over time: If health drops suddenly after a period of consistent performance, check whether anything changed in your source files around that time, such as the file structure, column names, or data types.

Best Practices

The following best practices help ensure your File-Based Imports run smoothly and your data remains clean and reliable.

Before configuring and running your import, ensure your source files are ready for a successful sync by reviewing the following:

• Validate your source data before configuring the import. Ensure that identity fields such as email, phone, or custom ID contain clean, non-null values, and that data types in your source columns match the mappings you intend to configure.
• Ensure phone numbers include a valid country code in E.164 format (for example, +919876543210) and that email addresses are properly formatted.
• Avoid including system event names, such as App Launched, in the event name column of your source files, as these cannot be imported from external sources.
• Remove or replace reserved or placeholder identity values such as null, 0, N/A, undefined, or none in the source before the import runs.
• Ensure each file is fully written and closed before it is placed in the storage bucket. CleverTap picks up files based on the timestamp in the file name and marks a file as Failed if the file is still being written when CleverTap starts fetching it.
• Keep each file under its size limit: 5 GB for CSV and 1 GB for Parquet. CleverTap marks larger files as Failed and does not process them.
• Confirm that your storage bucket credentials are valid and have not been rotated or updated since the import was last configured.

Monitor Imports

Review the following practices to ensure better import health and catch issues early:

• Review Stats after each run, especially for scheduled imports, to confirm the health percentage is at expected levels.
• For imports scheduled at short intervals, such as every 15 minutes, be aware that if a run takes longer than the scheduled interval to complete, the next run will be skipped automatically and resume from the one after. This will appear as a gap in the Stats table and is expected behavior.
• Stats are available for runs completed within the last 30 days. For long-term monitoring, note down or export health and record counts periodically if historical tracking is important for your team.
• If an import in a running state is manually stopped, stats will not be available for that run, even if some records were partially ingested. Allow imports to complete before stopping them where possible.

Error Reference

Use this section to identify and resolve validation errors that appear in the detail pane for failed records. Errors are grouped by import type.

Common Errors

The following errors apply to both user profiles and event imports:

User Profile Import Errors

The following errors may appear for failed records in a user profile import:

Event Import Errors

The following errors may appear in the detail pane for failed records in an event import: