# Running Imports

Once an importer is defined and registered, you can start an import process in several ways, depending on your use case.

# Artisan Commands

Laravel Ingest provides several Artisan commands for managing imports.

# ingest:run

The ingest:run command is perfect for manual or scheduled imports where the source file is accessible on a local or configured filesystem disk.

php artisan ingest:run {slug} {--file=} {--dry-run}

Argument/Option	Description
`slug`	The slug of the importer to run (e.g., `user-importer`)
`--file`	Path to the source file (required for `FILESYSTEM` sources)
`--dry-run`	Simulate the import without saving data

# Run a product import from a file on the default disk
php artisan ingest:run product-importer --file="imports/products.csv"

# Perform a dry run to check for errors
php artisan ingest:run product-importer --file="imports/products.csv" --dry-run

# ingest:list

List all registered importers and their configurations.

php artisan ingest:list

# ingest:status

Check the status of a specific import run.

php artisan ingest:status {id}

Argument	Description
`id`	The ID of the IngestRun to check

# ingest:cancel

Cancel a running import. This will stop processing new chunks but won't roll back already processed rows.

php artisan ingest:cancel {id}

Argument	Description
`id`	The ID of the IngestRun to cancel

# ingest:retry

Retry failed rows from a previous import run.

php artisan ingest:retry {id} {--dry-run}

Argument/Option	Description
`id`	The ID of the IngestRun to retry
`--dry-run`	Simulate the retry without saving data

# ingest:prune-files

Clean up old temporary and uploaded files to free disk space.

php artisan ingest:prune-files {--hours=24}

Option	Default	Description
`--hours`	`24`	Delete files older than this many hours

This command removes files from the ingest-temp and ingest-uploads directories that are older than the specified number of hours.

# Scheduling File Cleanup

Add to your routes/console.php or scheduler:

// Clean up files older than 24 hours, daily
Schedule::command('ingest:prune-files')->daily();

// Clean up files older than 6 hours, every hour
Schedule::command('ingest:prune-files --hours=6')->hourly();

# Row Log Pruning

To automatically prune old row logs (stored in ingest_rows table), add Laravel's model pruning command to your scheduler:

// In routes/console.php or App\Console\Kernel
Schedule::command('model:prune')->daily();

The retention period is configured via prune_days in config/ingest.php (default: 30 days).

# 2. Via API

Laravel Ingest automatically registers API endpoints to trigger and manage imports. These are ideal for integrations or when providing a user interface for uploads.

# File Uploads (`UPLOAD` source)

To start an import that uses SourceType::UPLOAD, send a multipart/form-data POST request.

Endpoint: POST /api/v1/ingest/upload/{importerSlug}
Body: Must contain a file field with the uploaded file. You can also include an optional dry_run field set to 1 or true.

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/users.csv" \
  -F "dry_run=1" \
  https://myapp.com/api/v1/ingest/upload/user-importer

# Triggering Other Sources (`FTP`, `URL`, etc.)

For importers that don't require a file upload (like FTP or URL sources), you can trigger them with a simple POST request.

Endpoint: POST /api/v1/ingest/trigger/{importerSlug}

curl -X POST \
  -H "Authorization: Bearer <token>" \
  https://myapp.com/api/v1/ingest/trigger/daily-stock-importer

# 3. Programmatically (Facade)

You can start an import directly from your application code using the Ingest Facade. This is useful for complex workflows, scheduled jobs, or custom controllers.

use LaravelIngest\Facades\Ingest;
use Illuminate\Support\Facades\Auth;

$slug = 'product-importer';
$filePath = 'imports/products.csv'; // Path on a configured disk
$user = Auth::user();

// Start the import
$ingestRun = Ingest::start(
    importer: $slug, 
    payload: $filePath, 
    user: $user,
    isDryRun: false
);

// $ingestRun is the Eloquent model for the newly created run.
echo "Started ingest run with ID: " . $ingestRun->id;