> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Import user events (CSV)

> Upload a CSV and enqueue user-event batch import using a saved mapping — via the gu1 batch import API for high-volume data loading.

## Endpoint

```
POST https://api.gu1.ai/batch-import/import/user-events
```

## Overview

**Content-Type:** `multipart/form-data`.

**Permissions:** `events:create`.

## Authentication

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Form fields

| Field                | Required | Description                                                                       |
| -------------------- | -------- | --------------------------------------------------------------------------------- |
| `file`               | Yes      | CSV file                                                                          |
| `mappingId`          | Yes      | Mapping with `target === user_event`                                              |
| `executeRules`       | No       | `true` (default) or `false`                                                       |
| `withAutoEntity`     | No       | `true` (default) or `false`                                                       |
| `batchErrorHandling` | No       | Row error policy — see below. Default **`continue_collect_errors`** when omitted. |

### Row error policy (`batchErrorHandling`)

| Value                                   | Behavior                                                                                                                                                                 |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`continue_collect_errors`** (default) | Valid rows are queued and imported. Rows that fail mapping validation (e.g. unmapped `eventType`) are recorded as preflight failures and appear in the job failures CSV. |
| **`rollback_all`**                      | If **any** row fails mapping validation, the request returns **`400`** and no job is created.                                                                            |
| **`stop_keep_success`**                 | Like continue for preflight; during processing, the worker stops after the first runtime row failure. Events created before that point are kept.                         |

Legacy alias: `stopOnFirstError=true` maps to **`stop_keep_success`**.

## Limits

|                           | Value                                                                                                      |
| ------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Files per request**     | **1** CSV                                                                                                  |
| **Max rows per import**   | By plan — [Bulk imports overview — Limits by plan](/en/api-reference/bulk-imports/overview#limits-by-plan) |
| **Server cap (optional)** | `USER_EVENT_BATCH_IMPORT_MAX_ROWS` may lower the plan limit                                                |
| **Over limit**            | **`400`** `TOO_MANY_ITEMS`                                                                                 |

## Success response

**`202 Accepted`**

```json theme={null}
{
  "success": true,
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "totalItems": 1200,
  "preflightFailures": 3,
  "message": "User event import queued"
}
```

* **`totalItems`** — valid rows queued + preflight failures (mapping errors skipped under continue policy).
* **`preflightFailures`** — rows that failed mapping validation before the worker ran (download failures CSV from [unified history](/en/api-reference/bulk-imports/list-unified-history) when the job completes).

## Pre-job errors

| HTTP    | `error.code`       | When                                                                                |
| ------- | ------------------ | ----------------------------------------------------------------------------------- |
| **400** | `VALIDATION_ERROR` | `rollback_all` and one or more rows fail mapping (`details`: structured row errors) |
| **400** | `NO_VALID_ROWS`    | Every row failed mapping under continue policy                                      |

See [Batch import failure codes](/en/api-reference/bulk-imports/batch-import-failure-codes).

See also: [Bulk imports overview](/en/api-reference/bulk-imports/overview).